1## BLE蓝牙使用说明文档 2 3 本文档主要介绍了蓝牙专项测试程序的BLE蓝牙部分(ohos.bluetoothManager.d.ts)的功能使用说明。 4 5#### 从主界面跳转到BLE蓝牙部分 6 7#### setting界面 8 9点击"switch"按钮 ，设置本设备的BLE参数与配置 10 11>"BLE扫描过滤参数"，"BLE扫描配置" 默认都为true，是勾选的；值也是默认填好的。**如果不需要更改，无需打开BleFilter界面**。 12> 13>外设MAC地址填了默认值，可根据自己的连接需求更改。 14> 15>BLE扫描过滤参数包括： 16> 17>- 本机MAC地址。 18>- 本机name。 19>- 本机的serviceUUid。 20> 21>BLE扫描配置包括： 22> 23>- interval值 （默认值：0） 24> 25>- dutyMode：(默认值：LOW_POWER ) 26> 27> > - LOW_POWER 28> > - BALANCED 29> > - LOW_LATENCY 30> 31>- matchMode:(默认值: MATCH_MODE_AGGRESSIVE) 32> 33> >- MATCH_MODE_AGGRESSIVE 34> >- MATCH_MODE_STICKY 35 36 37 38#### BLE蓝牙的主要接口(ohos.bluetoothManager.d.ts) 39 40| method名称 | API名称 | 所需参数 | 返回值 | 备注 | 41| :-------------------------: | :--------------------: | :----------------------------------------------------------: | :-----------: | :--: | 42| 开始BLE扫描 | startBLEScan | (filters: Array<ScanFilter>, options?: ScanOptions) | void | | 43| 停止BLE扫描 | stopBLEScan | () | void | | 44| 订阅BLE设备发现上报事件 | on. BLEDevice | (type: “BLEDeviceFind”, callback: Callback<Array<ScanResult>>) | void | | 45| 取消订阅BLE设备发现上报事件 | off.BLEDeviceFind | (type: “BLEDeviceFind”, callback?: Callback<Array<ScanResult>>) | void | | 46| 获取连接的BLE设备 | getConnectedBLEDevices | () | Array<string> | | 47 48 49 50注：此处的"创建Gatt服务器"，"创建Gatt客户端"功能只是写了个壳子，其主要功能在Gatt界面中。 51 52 53 54>| 参数名 | 类型 | 必填 | 说明 | 55>| :-----: | :-------------------: | :--- | :----------------------------------------------------------: | 56>| filters | Array<**ScanFilter**> | 是 | 表示扫描结果过滤策略集合，如果不使用过滤的方式，该参数设置为null。 | 57>| options | **ScanOptions** | 否 | 表示扫描的参数配置，可选参数。 | 58> 59> 60> 61>#### ScanFilter 扫描过滤参数 62> 63>| 名称 | 类型 | 可读 | 可写 | 说明 | 64>| :-------------------------- | :---------- | :--- | :--- | :----------------------------------------------------------- | 65>| deviceId | string | 是 | 是 | 表示过滤的BLE设备地址，例如：“XX:XX:XX:XX:XX:XX”。 | 66>| name | string | 是 | 是 | 表示过滤的BLE设备名。 | 67>| serviceUuid | string | 是 | 是 | 表示过滤包含该UUID服务的设备，例如：00001888-0000-1000-8000-00805f9b34fb。 | 68>| serviceUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 69>| serviceSolicitationUuid | string | 是 | 是 | 表示过滤包含该UUID服务请求的设备，例如：00001888-0000-1000-8000-00805F9B34FB。 | 70>| serviceSolicitationUuidMask | string | 是 | 是 | 表示过滤包含该UUID服务请求掩码的设备，例如：FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF。 | 71>| serviceData | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据的设备，例如：[0x90,0x00,0xF1,0xF2]。 | 72>| serviceDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该服务相关数据掩码的设备，例如：[0xFF,0xFF,0xFF,0xFF]。 | 73>| manufactureId | number | 是 | 是 | 表示过滤包含该制造商ID的设备，例如：0x0006。 | 74>| manufactureData | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据的设备，例如：[0x1F,0x2F,0x3F]。 | 75>| manufactureDataMask | ArrayBuffer | 是 | 是 | 表示过滤包含该制造商相关数据掩码的设备，例如：[0xFF,0xFF,0xFF]。 | 76> 77> 78> 79>#### ScanOptions 扫描的配置参数 80> 81>| 名称 | 类型 | 可读 | 可写 | 说明 | 82>| :-------- | :------------ | :--- | :--- | :------------------------------------------------------ | 83>| interval | number | 是 | 是 | 表示扫描结果上报延迟时间，默认值为0。 | 84>| dutyMode | **ScanDuty** | 是 | 是 | 表示扫描模式，默认值为SCAN_MODE_LOW_POWER。 | 85>| matchMode | **MatchMode** | 是 | 是 | 表示硬件的过滤匹配模式，默认值为MATCH_MODE_AGGRESSIVE。 | 86> 87> 88> 89>#### ScanDuty 枚举，扫描模式 90> 91>| 名称 | 值 | 说明 | 92>| :-------------------: | :--: | :----------------------: | 93>| SCAN_MODE_LOW_POWER | 0 | 表示低功耗模式，默认值。 | 94>| SCAN_MODE_BALANCED | 1 | 表示均衡模式。 | 95>| SCAN_MODE_LOW_LATENCY | 2 | 表示低延迟模式。 | 96> 97> 98> 99>#### MatchMode 枚举，硬件过滤匹配模式 100> 101>| 名称 | 值 | 说明 | 102>| :-------------------: | :--: | :----------------------------------------------------------: | 103>| MATCH_MODE_AGGRESSIVE | 1 | 表示硬件上报扫描结果门限较低，比如扫描到的功率较低或者一段时间扫描到的次数较少也触发上报，默认值。 | 104>| MATCH_MODE_STICKY | 2 | 表示硬件上报扫描结果门限较高，更高的功率门限以及扫描到多次才会上报。 | 105> 106> 107> 108>#### ScanResult 扫描结果上报数据 109> 110>| 名称 | 类型 | 可读 | 可写 | 说明 | 111>| :------: | :---------: | :--: | :--: | :-----------------------------------------------: | 112>| deviceId | string | 是 | 否 | 表示扫描到的设备地址，例如：“XX:XX:XX:XX:XX:XX”。 | 113>| rssi | number | 是 | 否 | 表示扫描到的设备的rssi值。 | 114>| data | ArrayBuffer | 是 | 否 | 表示扫描到的设备发送的广播包。 | 115 116 117 118#### 功能 119 120**"蓝牙打开"是其他功能测试的前提** 121 1221. 开始/停止BLE扫描 123 124 - 使用指导： 125 126 > 开始BLE扫描： 127 > 128 > - 开始扫描具有筛选器的指定BLE设备。 129 > - filters表示用于筛选出指定设备的筛选器列表。 130 > - options指示扫描的参数，如果用户未指定值，将使用默认值。 131 > 132 > 停止BLE扫描。 133 134 - 限制条件： 135 136 - 只能扫描到指定BLE设备。 137 - 如果不想使用筛选器，请将此参数filters设置为｛@code null｝。 138 - ｛interval｝设置为0， 139 - ｛扫描选项#dutyMode｝设置成｛SCAN_MODE_LOW_POWER｝并且{ScanOptions#matchMode}设置为{ MATCH_MODE_AGGRESSIVE} 140 - @throws { BusinessError } 201 - Permission denied. 141 - @throws { BusinessError } 401 - Invalid parameter. 142 - @throws { BusinessError } 801 - Capability not supported. 143 - @throws { BusinessError } 2900001 - Service stopped. 144 - @throws { BusinessError } 2900003 - Bluetooth switch is off. 145 - @throws { BusinessError } 2900099 - Operation failed. 146 147 - 验证方法：根据弹窗消息查看已扫描到的BLE 148 149 150 1512. BLE设备查找变化 152 153 - 使用指导：为回调函数，用来监听相关类型事件的变化，并弹窗显示信息。 154 155 - 订阅BLE扫描结果。 156 - type为要侦听的扫描结果事件的类型。 157 - callback回调用于侦听扫描结果事件。 158 - @throws { BusinessError } 201 - Permission denied. 159 - @throws { BusinessError } 401 - Invalid parameter. 160 - @throws { BusinessError } 801 - Capability not supported. 161 - @throws { BusinessError } 2900099 - Operation failed. 162 163 - 限制条件：需要在相关类型事件发生改变前，开启监听。 164 165 - 验证方法：在事件变化后，查看是否有弹窗信息显示。 166 167 168 1693. 获取连接的BLE设备 170 171 - 使用指导：点击后，可获取到处于连接状态的设备列表。 172 - 限制条件： 173 - 开始BLE扫描，并发现了可连接的设备，连接后，才可以获取此设备的相关信息。 174 - @throws { BusinessError } 201 - Permission denied. 175 - @throws { BusinessError } 801 - Capability not supported. 176 - @throws { BusinessError } 2900001 - Service stopped. 177 - @throws { BusinessError } 2900003 - Bluetooth switch is off. 178 - @throws { BusinessError } 2900099 - Operation failed. 179 - 验证方法：在设备设置中，查看已经连接的设备。