Bluetooth 教程

了解如何使用低功耗蓝牙

通过本节，你将学会：

  • 初始化蓝牙模块
  • 搜索周围设备
  • 连接设备
  • 获取设备服务信息
  • 获取设备特征值信息
  • 向设备写入数据
  • 读取设备数据
  • 监听设备数据变化
  • 注销蓝牙模块

使用方法

初始化蓝牙模块

为了使用蓝牙功能，你需要先初始化蓝牙模块。除了设置状态监听以外，所有的蓝牙接口都需要在初始化完成以后才能正常使用。

  1. //初始化蓝牙模块
  2. bluetooth.openAdapter({
  3.   //是否打开系统蓝牙开关，默认false
  4.   operateAdapter: true,
  5.   success: function() {
  6.     console.log('success')
  7.   },
  8.   fail: function(data, code) {
  9.     console.log(`handling fail, code = ${code}`)
  10.     if (code === 10001) {
  11.       //蓝牙未打开，提示用户打开蓝牙
  12.     }
  13.   },
  14.   complete: function() {
  15.     console.log('complete')
  16.   }
  17. })

搜索周围设备

你可以通过搜索操作，发现周围的低功耗蓝牙设备。在进行扫描前，你需要注册设备发现回调以及时接收搜索结果

  1. //在扫描之前先注册设备发现回调
  2. bluetooth.ondevicefound = function (data) {
  3.   console.log("new device list has founded");
  4.   data.devices.forEach(device => {
  5.     //发现所需设备后停止扫描
  6.     bluetooth.stopDevicesDiscovery();
  7.     _this.deviceId = device.deviceId;
  9.     console.log(`handling find new devive:${JSON.stringify(device)}`);
  10.     console.log(`handling advertisData = ${_this.ab2hex(device.advertisData)}`);
  11.     for (let key in device.serviceData) {
  12.       console.log(
  13.         `handling serviceData: uuid = ${key}, serviceData = ${_this.ab2hex(device.serviceData[key])}`
  14.       );
  15.     }
  16.   });
  17. };
  18. //开始扫描
  19. bluetooth.startDevicesDiscovery({
  20.   //指定设备uuid，支持16-bit,32-bit,128-bit uuid,不填则扫描周围所有设备
  21.   services: ["1105"],
  22.   //是否允许重复设备上报，如果不需要监听广播包数据，建议不设置此项，默认值为false
  23.   allowDuplicatesKey: false,
  24.   //上报间隔，单位毫秒，为0则立即上报，默认值为0
  25.   interval: 1000,
  26.   success: function () {
  27.     console.log("success");
  28.   }
  29. });

连接设备

在操作设备前，你需要先连接设备，连接操作可以通过deviceId直接进行，扫描并不是必要的操作。在连接前，你可以注册设备连接状态接口来监听设备断连状态

  1. //注册设备连接状态监听
  2. bluetooth.onbleconnectionstatechange = function (data) {
  3.   console.log(`handling device state change: deviceId = ${data.deviceId}, connected = ${data.connected}`)
  4.   //更新设备连接状态
  5.   _this.connected = data.connected
  6.   if (data.connected) {
  7.     //目标设备连接后，获取服务列表
  8.     _this.getServices()
  9.   } else {
  10.     //做断开连接的相关操作，比如重新连接，或者重新扫描等
  11.   }
  12. }
  13. //连接设备
  14. bluetooth.createBLEConnection({
  15.   deviceId: _this.deviceId,
  16.   success: function () {
  17.     console.log("success")
  18.   },
  19.   fail: function (data, code) {
  20.     console.log(`handling fail, code = ${code}`)
  21.   },
  22.   complete: function () {
  23.     console.log("complete")
  24.   }
  25. })

获取设备服务信息

每个设备都会定义若干个服务，你可以从中获取需要操作的服务信息

  1. bluetooth.getBLEDeviceServices({
  2.   deviceId: _this.deviceId,
  3.   success: function (data) {
  4.     data.services.forEach(service => {
  5.       console.log(`handling device services: uuid = ${service.uuid}, isPrimary = ${service.isPrimary}`)
  6.       //获取需要的服务，可以根据设备定义的uuid筛选
  7.       if (service.isPrimary) {
  8.         _this.serviceId = service.uuid
  9.         //获取特征值列表
  10.         _this.getCharacteristics()
  11.       }
  12.     })
  13.   },
  14.   fail: function (data, code) {
  15.     console.log(`handling fail, code = ${code}`)
  16.   },
  17.   complete: function () {
  18.     console.log("complete")
  19.   }
  20. })

获取设备特征值信息

每个服务内会定义若干个特征值，你可以从中获取需要操作的特征值信息

  1. bluetooth.getBLEDeviceCharacteristics({
  2.   deviceId: _this.deviceId,
  3.   serviceId: _this.serviceId,
  4.   success: function (data) {
  5.     data.characteristics.forEach(characteristic => {
  6.       console.log(`handling device characteristic : ${JSON.stringify(characteristic)}`)
  7.       //获取需要的特征值，可以根据设备定义的uuid筛选
  8.       if (characteristic.properties.write) {
  9.         _this.writeCharacteristicId = characteristic.uuid
  10.       } else if (characteristic.properties.read) {
  11.         _this.readCharacteristicId = characteristic.uuid
  12.       } else if (characteristic.properties.notify || characteristic.properties.indicate) {
  13.         _this.notifyCharacteristicId = characteristic.uuid
  14.       }
  15.     })
  16.   },
  17.   fail: function (data, code) {
  18.     console.log(`handling fail, code = ${code}`)
  19.   },
  20.   complete: function () {
  21.     console.log("complete")
  22.   }
  23. })

向设备写入数据

通过获取到的服务与特征值信息，可以向设备对应的特征值写入数据，需要该特征值支持 write

  1. let buffer = new ArrayBuffer(2)
  2. let dataView = new DataView(buffer)
  3. dataView.setUint8(0, 0)
  4. dataView.setUint8(1, 0xf)
  5. bluetooth.writeBLECharacteristicValue({
  6.   // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound接口中获取
  7.   deviceId: _this.deviceId,
  8.   // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  9.   serviceId: _this.serviceId,
  10.   // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  11.   characteristicId: _this.writeCharacteristicId,
  12.   // 这里的value是ArrayBuffer类型
  13.   value: buffer,
  14.   success: function () {
  15.     console.log("success")
  16.   },
  17.   fail: function (data, code) {
  18.     console.log(`handling fail, code = ${code}`)
  19.   },
  20.   complete: function () {
  21.     console.log("complete")
  22.   }
  23. })

读取设备数据

通过获取到的服务与特征值信息，可以读取设备对应特征值数据，需要该特征值支持 read，读取到的设备信息会通过onblecharacteristicvaluechange监听接口上报，此接口蓝牙模块通用，无需重复注册

  1. //注册特征值改变监听
  2. bluetooth.onblecharacteristicvaluechange = function (data) {
  3.   console.log(`handling characteristic value change: deviceId = ${data.deviceId}, serviceId = ${data.serviceId}, characteristicId = ${data.characteristicId}, value = ${_this.ab2hex(data.value)}`)
  4. }
  5. bluetooth.readBLECharacteristicValue({
  6.   // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  7.   deviceId: _this.deviceId,
  8.   // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  9.   serviceId: _this.serviceId,
  10.   // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  11.   characteristicId: _this.readCharacteristicId,
  12.   success: function () {
  13.     // 执行操作成功，读取的值会在onblecharacteristicvaluechange 接口中上报
  14.     console.log("success")
  15.   }
  16. })

监听设备数据变化

通过获取到的服务与特征值信息，可以开启或者关闭设备相应的特征值变化时的通知功能，需要该特征值支持 notify 或者 indicate，读取到的设备信息会通过onblecharacteristicvaluechange监听接口上报，此接口蓝牙模块通用，无需重复注册

  1. //注册特征值改变监听
  2. bluetooth.onblecharacteristicvaluechange = function (data) {
  3.   console.log(`handling characteristic value change: deviceId = ${data.deviceId}, serviceId = ${data.serviceId}, characteristicId = ${data.characteristicId}, value = ${_this.ab2hex(data.value)}`)
  4. }
  5. bluetooth.notifyBLECharacteristicValueChange({
  6.   // 启用 notify 功能,为true则开启通知
  7.   state: enable,
  8.   // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  9.   deviceId: _this.deviceId,
  10.   // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  11.   serviceId: _this.serviceId,
  12.   // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  13.   characteristicId: _this.notifyCharacteristicId,
  14.   success: function () {
  15.     // 执行操作成功，读取的值会在onblecharacteristicvaluechange 接口中上报
  16.     _this.notifyEnabled = enable
  17.     console.log("success")
  18.   },
  19.   fail: function (data, code) {
  20.     console.log(`handling fail, code = ${code}`)
  21.   },
  22.   complete: function () {
  23.     console.log("complete")
  24.   }
  25. })

注销蓝牙模块

在不需要使用蓝牙时，需要注销蓝牙模块，以释放系统资源

  1. //取消不需要的状态监听
  2. bluetooth.onadapterstatechange = null
  3. bluetooth.onbleconnectionstatechange = null
  4. bluetooth.onblecharacteristicvaluechange = null
  5. bluetooth.ondevicefound = null
  7. //注销蓝牙模块
  8. bluetooth.closeAdapter({
  9.   //是否关闭系统蓝牙开关，默认false，此操作会直接关闭系统蓝牙，为了不影响用户其他蓝牙设备的体验，不建议设置为true
  10.   operateAdapter: false,
  11.   success: function () {
  12.     console.log("success");
  13.   },
  14.   fail: function (data, code) {
  15.     console.log(`handling fail, code = ${code}`);
  16.   },
  17.   complete: function () {
  18.     console.log("complete");
  19.   }
  20. });

示例代码如下：

  1. <template>
  2.   <div class="doc-page">
  3.     <div class="item-container">
  4.       <text></text>
  5.       <input type="button" class="btn" onclick="startDiscovery" value="扫描设备" />
  6.       <input type="button" class="btn" onclick="createConnection" value="连接设备" />
  7.       <input type="button" class="btn" onclick="closeConnection" value="断开设备" />
  8.     </div>
  9.     <div class="item-container" if=false>
  10.       <input type="button" class="btn" onclick="write" value="写入数据" />
  11.       <input type="button" class="btn" onclick="read" value="读取数据" />
  13.     </div>
  14.   </div>
  15. </template>
  17. <style>
  18.   .doc-page {
  19.     flex: 1;
  20.     flex-direction: column;
  21.   }
  23.   .item-container {
  24.     flex - direction: column;
  25.     margin-bottom: 50px;
  26.     margin-right: 60px;
  27.     margin-left: 60px;
  28.   }
  30.   .text {
  31.     width: 100%;
  32.     margin-top: 5px;
  33.     background-color: white;
  34.     padding: 3px;
  35.     margin-top: 1px;
  36.     font-size: 28px;
  37.     color: black;
  38.   }
  40.   .btn {
  41.     height: 80px;
  42.     text-align: center;
  43.     border-radius: 5px;
  44.     margin-right: 60px;
  45.     margin-left: 60px;
  46.     margin-bottom: 50px;
  47.     color: #ffffff;
  48.     font-size: 30px;
  49.     background-color: #0faeff;
  50.     line-height: 80px;
  51.   }
  52. </style>
  54. <script>
  55.   import bluetooth from "@system.bluetooth";
  57.   export default {
  58.     private: {
  59.       connected: false,
  60.       notifyEnabled: false,
  61.       deviceId: '',
  62.       readCharacteristicId: '',
  63.       writeCharacteristicId: '',
  64.       notifyCharacteristicId: ''
  65.     },
  66.     //arrayBuffer转String
  67.     ab2hex(buffer) {
  68.       var hexArr = Array.prototype.map.call(
  69.         new Uint8Array(buffer),
  70.         function (bit) {
  71.           return ("00" + bit.toString(16)).slice(-2);
  72.         });
  73.       return hexArr.join("");
  74.     },
  75.     //在页面初始化时进行蓝牙模块初始化操作
  76.     onInit() {
  77.       let _this = this
  78.       //注册蓝牙适配器监听
  79.       bluetooth.onadapterstatechange = function (data) {
  80.         console.log("adapterState changed, now is", data.available);
  81.       };
  83.       //注册设备连接状态监听
  84.       bluetooth.onbleconnectionstatechange = function (data) {
  85.         console.log(`handling device state change: deviceId = ${data.deviceId}, connected = ${data.connected}`)
  86.         //更新设备连接状态
  87.         _this.connected = data.connected
  88.         if (data.connected) {
  89.           //目标设备连接后，获取服务列表
  90.           _this.getServices()
  91.         } else {
  92.           //做断开连接的相关操作，比如重新连接，或者重新扫描等
  93.         }
  94.       }
  96.       //注册特征值改变监听
  97.       bluetooth.onblecharacteristicvaluechange = function (data) {
  98.         console.log(`handling characteristic value change: deviceId = ${data.deviceId}, serviceId = ${data.serviceId}, characteristicId = ${data.characteristicId}, value = ${_this.ab2hex(data.value)}`)
  99.       }
  101.       //初始化蓝牙模块
  102.       bluetooth.openAdapter({
  103.         //是否打开系统蓝牙开关，默认false
  104.         operateAdapter: true,
  105.         success: function () {
  106.           console.log("success");
  107.         },
  108.         fail: function (data, code) {
  109.           console.log(`handling fail, code = ${code}`);
  110.           if (code === 10001) {
  111.             //蓝牙未打开，提示用户打开蓝牙
  112.           }
  113.         },
  114.         complete: function () {
  115.           console.log("complete");
  116.         }
  117.       });
  118.     },
  119.     //在结束时注销蓝牙模块
  120.     onDestroy() {
  121.       //取消不需要的状态监听
  122.       bluetooth.onadapterstatechange = null
  123.       bluetooth.onbleconnectionstatechange = null
  124.       bluetooth.onblecharacteristicvaluechange = null
  125.       bluetooth.ondevicefound = null
  127.       //注销蓝牙模块
  128.       bluetooth.closeAdapter({
  129.         //是否关闭系统蓝牙开关，默认false，此操作会直接关闭系统蓝牙，为了不影响用户其他蓝牙设备的体验，不建议设置为true
  130.         operateAdapter: false,
  131.         success: function () {
  132.           console.log("success");
  133.         },
  134.         fail: function (data, code) {
  135.           console.log(`handling fail, code = ${code}`);
  136.         },
  137.         complete: function () {
  138.           console.log("complete");
  139.         }
  140.       });
  141.     },
  142.     startDiscovery() {
  143.       let _this = this
  144.       //在扫描之前先注册设备发现回调
  145.       bluetooth.ondevicefound = function (data) {
  146.         console.log("new device list has founded");
  147.         data.devices.forEach(device => {
  148.           //发现所需设备后停止扫描
  149.           bluetooth.stopDevicesDiscovery();
  150.           _this.deviceId = device.deviceId;
  152.           console.log(`handling find new devive:${JSON.stringify(device)}`);
  153.           console.log(`handling advertisData = ${_this.ab2hex(device.advertisData)}`);
  154.           for (let key in device.serviceData) {
  155.             console.log(
  156.               `handling serviceData: uuid = ${key}, serviceData = ${_this.ab2hex(device.serviceData[key])}`
  157.             );
  158.           }
  159.         });
  160.       };
  161.       //开始扫描
  162.       bluetooth.startDevicesDiscovery({
  163.         //指定设备uuid，支持16-bit,32-bit,128-bit uuid,不填则扫描周围所有设备
  164.         services: ["1105"],
  165.         //是否允许重复设备上报，如果不需要监听广播包数据，建议不设置此项，默认值为false
  166.         allowDuplicatesKey: false,
  167.         success: function () {
  168.           console.log("success");
  169.         }
  170.       });
  171.     },
  172.     createConnection() {
  173.       let _this = this
  174.       //连接设备
  175.       bluetooth.createBLEConnection({
  176.         deviceId: _this.deviceId,
  177.         success: function () {
  178.           console.log("success")
  179.         },
  180.         fail: function (data, code) {
  181.           console.log(`handling fail, code = ${code}`)
  182.         },
  183.         complete: function () {
  184.           console.log("complete")
  185.         }
  186.       })
  187.     },
  188.     closeConnection() {
  189.       let _this = this
  190.       bluetooth.closeBLEConnection({
  191.         deviceId: _this.deviceId,
  192.         success: function () {
  193.           console.log("success")
  194.         },
  195.         fail: function (data, code) {
  196.           console.log(`handling fail, code = ${code}`)
  197.         },
  198.         complete: function () {
  199.           console.log("complete")
  200.         }
  201.       })
  202.     },
  203.     getServices() {
  204.       let _this = this
  205.       bluetooth.getBLEDeviceServices({
  206.         deviceId: _this.deviceId,
  207.         success: function (data) {
  208.           data.services.forEach(service => {
  209.             console.log(`handling device services: uuid = ${service.uuid}, isPrimary = ${service.isPrimary}`)
  210.             //获取需要的服务，可以根据设备定义的uuid筛选
  211.             if (service.isPrimary) {
  212.               _this.serviceId = service.uuid
  213.               //获取特征列表
  214.               _this.getCharacteristics()
  215.             }
  216.           })
  217.         },
  218.         fail: function (data, code) {
  219.           console.log(`handling fail, code = ${code}`)
  220.         },
  221.         complete: function () {
  222.           console.log("complete")
  223.         }
  224.       })
  225.     },
  226.     getCharacteristics() {
  227.       let _this = this
  228.       bluetooth.getBLEDeviceCharacteristics({
  229.         deviceId: _this.deviceId,
  230.         serviceId: _this.serviceId,
  231.         success: function (data) {
  232.           data.characteristics.forEach(characteristic => {
  233.             console.log(`handling device characteristic : ${JSON.stringify(characteristic)}`)
  234.             //获取需要的特征，可以根据设备定义的uuid筛选
  235.             if (characteristic.properties.write) {
  236.               _this.writeCharacteristicId = characteristic.uuid
  237.             } else if (characteristic.properties.read) {
  238.               _this.readCharacteristicId = characteristic.uuid
  239.             } else if (characteristic.properties.notify || characteristic.properties.indicate) {
  240.               _this.notifyCharacteristicId = characteristic.uuid
  241.             }
  242.           })
  243.         },
  244.         fail: function (data, code) {
  245.           console.log(`handling fail, code = ${code}`)
  246.         },
  247.         complete: function () {
  248.           console.log("complete")
  249.         }
  250.       })
  251.     },
  252.     write() {
  253.       let _this = this
  254.       let buffer = new ArrayBuffer(2)
  255.       let dataView = new DataView(buffer)
  256.       dataView.setUint8(0, 0)
  257.       dataView.setUint8(1, 0xf)
  258.       bluetooth.writeBLECharacteristicValue({
  259.         // 这里的 deviceId 需要在 getBluetoothDevices 或 onBluetoothDeviceFound接口中获取
  260.         deviceId: _this.deviceId,
  261.         // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  262.         serviceId: _this.serviceId,
  263.         // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  264.         characteristicId: _this.writeCharacteristicId,
  265.         // 这里的value是ArrayBuffer类型
  266.         value: buffer,
  267.         success: function () {
  268.           console.log("success")
  269.         },
  270.         fail: function (data, code) {
  271.           console.log(`handling fail, code = ${code}`)
  272.         },
  273.         complete: function () {
  274.           console.log("complete")
  275.         }
  276.       })
  277.     },
  278.     read() {
  279.       let _this = this
  280.       bluetooth.readBLECharacteristicValue({
  281.         // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  282.         deviceId: _this.deviceId,
  283.         // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  284.         serviceId: _this.serviceId,
  285.         // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  286.         characteristicId: _this.readCharacteristicId,
  287.         success: function () {
  288.           // 执行操作成功，读取的值会在onblecharacteristicvaluechange 接口中上报
  289.           console.log("success")
  290.         }
  291.       })
  292.     },
  293.     notifyDevice(enable) {
  294.       let _this = this
  295.       bluetooth.notifyBLECharacteristicValueChange({
  296.         // 启用 notify 功能
  297.         state: enable,
  298.         // 这里的 deviceId 需要已经通过 createBLEConnection 与对应设备建立链接
  299.         deviceId: _this.deviceId,
  300.         // 这里的 serviceId 需要在 getBLEDeviceServices 接口中获取
  301.         serviceId: _this.serviceId,
  302.         // 这里的 characteristicId 需要在 getBLEDeviceCharacteristics 接口中获取
  303.         characteristicId: _this.notifyCharacteristicId,
  304.         success: function () {
  305.           // 执行操作成功，读取的值会在onblecharacteristicvaluechange 接口中上报
  306.           _this.notifyEnabled = enable
  307.           console.log("success")
  308.         },
  309.         fail: function (data, code) {
  310.           console.log(`handling fail, code = ${code}`)
  311.         },
  312.         complete: function () {
  313.           console.log("complete")
  314.         }
  315.       })
  316.     }
  317.   };
  318. </script>