# FastBle **Repository Path**: hihopeorg/FastBle ## Basic Information - **Project Name**: FastBle - **Description**: No description available - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2021-02-27 - **Last Updated**: 2024-02-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FastBle **本项目是基于开源项目FastBle进行ohos化的移植和开发的，可以通过项目标签以及github地址（https://github.com/Jasonchenlijian/FastBle ）追踪到原项目版本** ## 项目介绍 - 项目名称：开源弹幕解析绘制引擎项目 - 所属系列：ohos的第三方组件适配移植 - 功能： 1. 过滤，扫描，链接，读取，写入，通知订阅和取消的简单方式 2. 支持获取信号强度和设置最大传输单元 3. 支持自定义扫描规则 4. 支持多设备连接 5. 支持重新连接 6. 连接或操作时支持配置超时 - 项目移植状态：完成 - 调用差异：无 - 项目作者和维护人： hihope - 联系方式：hihope@hoperun.com - 原项目Doc地址：https://github.com/Jasonchenlijian/FastBle - 原项目基线版本：v2.3.2,sha1:95a859b5fb7b7de6dcf7dab2ed9fd7a43435f1dd - 编程语言：Java ## 效果展示： ## 安装教程 方法1. 1. implementation 'com.clj.fastble:FastBleLib:1.0.0' 2. 将library引入工程后，在主工程build.gradle 中加入compile project(path: ': fastblelib) 方法2. 1. 在工程的build.gradle的allprojects中，添加HAR所在的Maven仓地址 ``` repositories { maven { url 'http://106.15.92.248:8081/repository/Releases/' } } ``` 2. 在应用模块的build.gradle的dependencies闭包中，添加如下代码: ``` dependencies { implementation 'com.clj.fastble.ohos:FastBleLib:1.0.0' } ``` ## 使用说明 ``` 动态权限权限申请 "reqPermissions": [ { "name": "ohos.permission.LOCATION", "reason": "blu_location", "usedScene": { "ability": [ "com.inuker.bluetooth.MainAbility" ], "when": "always" } }, { "name": "ohos.permission.USE_BLUETOOTH" }, { "name": "ohos.permission.DISCOVER_BLUETOOTH" } ] private void initPermission() { if (verifySelfPermission("ohos.permission.LOCATION") != IBundleManager.PERMISSION_GRANTED) { // 应用未被授予权限 if (canRequestPermission("ohos.permission.LOCATION")) { // 是否可以申请弹框授权(首次申请或者用户未选择禁止且不再提示) requestPermissionsFromUser( new String[]{"ohos.permission.LOCATION"}, MY_PERMISSIONS_REQUEST_LOCATION); } else { // 显示应用需要权限的理由，提示用户进入设置授权 } } else { // 权限已被授予 } } @Override public void onRequestPermissionsFromUserResult(int requestCode, String[] permissions, int[] grantResults) { switch (requestCode) { case MY_PERMISSIONS_REQUEST_LOCATION: { // 匹配requestPermissions的requestCode if (grantResults.length > 0 && grantResults[0] == IBundleManager.PERMISSION_GRANTED) { // 权限被授予 // 注意：因时间差导致接口权限检查时有无权限，所以对那些因无权限而抛异常的接口进行异常捕获处理 sendMessage(); } else { // 权限被拒绝 } return; } } } ``` - ### 初始化 BleManager.getInstance().init(getApplication()); - ### 打开或关闭蓝牙 ``` void enableBluetooth() void disableBluetooth() ``` - ### 初始化配置 BleManager.getInstance() .enableLog(true) .setReConnectCount(1, 5000) .setSplitWriteNum(20) .setConnectOverTime(10000) .setOperateTimeout(5000); - ### 配置扫描规则 `void initScanRule(BleScanRuleConfig scanRuleConfig)` BleScanRuleConfig scanRuleConfig = new BleScanRuleConfig.Builder() .setServiceUuids(serviceUuids) .setDeviceName(true, names) .setDeviceMac(mac) .setAutoConnect(isAutoConnect) .setScanTimeOut(10000) .build(); BleManager.getInstance().initScanRule(scanRuleConfig); Tips: —在对设备进行扫描之前，可以配置扫描规则，将匹配程序的设备过滤掉。 ​ —“未配置”为默认参数 - ### 扫描设备 `void scan(BleScanCallback callback)` BleManager.getInstance().scan(new BleScanCallback() { @Override public void onScanStarted(boolean success) { } @Override public void onScanning(BleDevice bleDevice) { } @Override public void onScanFinished(List scanResultList) { } }); Tips: —扫描和过滤过程在工作线程中进行，所以不会影响主线程的UI操作。最终，每个回调结果都会返回到主线程。 - ### 连接设备 `BluetoothGatt connect(BleDevice bleDevice, BleGattCallback bleGattCallback)` BleManager.getInstance().connect(bleDevice, new BleGattCallback() { @Override public void onStartConnect() { } @Override public void onConnectFail(BleDevice bleDevice, BleException exception) { } @Override public void onConnectSuccess(BleDevice bleDevice, BluetoothGatt gatt, int status) { } @Override public void onDisConnected(boolean isActiveDisConnected, BleDevice bleDevice, BluetoothGatt gatt, int status) { } }); Tips: —在某些类型的手机上，connectGatt必须在主线程上有效。非常推荐将连接进程放在主线程中。 —连接失败后，重新连接:框架包含了连接失败后的重新连接机制，可以配置重新连接的时间和间隔。当然，你也可以自动调用' onConnectFail '回调中的' connect '方法。 —连接断开并重新连接:你可以在' onDisConnected '回调方法中再次调用' connect '方法。 —为了保证重新连接的成功率，建议间隔一段时间重新连接。 —部分型号出现故障时，短时间内无法扫描设备。它们可以直接通过设备对象或设备MAC连接，而不需要扫描。 - ### 连接MAC `BluetoothGatt connect(String mac, BleGattCallback bleGattCallback)` ``` BleManager.getInstance().connect(mac, new BleGattCallback() { @Override public void onStartConnect() { } @Override public void onConnectFail(BleDevice bleDevice, BleException exception) { } @Override public void onConnectSuccess(BleDevice bleDevice, BluetoothGatt gatt, int status) { } @Override public void onDisConnected(boolean isActiveDisConnected, BleDevice bleDevice, BluetoothGatt gatt, int status) { } }); ``` Tips: —这种方法可以尝试直接连接到Mac周围的BLE设备，而不需要扫描。 —在很多使用场景下，建议APP保存用户习惯设备的Mac，然后用这种方法连接，这样会大大提高连接效率。 - ### 扫描并连接 对第一台符合扫描规则的设备进行扫描后，停止扫描并连接设备。 `void scanAndConnect(BleScanAndConnectCallback callback)` BleManager.getInstance().scanAndConnect(new BleScanAndConnectCallback() { @Override public void onScanStarted(boolean success) { } @Override public void onScanFinished(BleDevice scanResult) { } @Override public void onStartConnect() { } @Override public void onConnectFail(BleDevice bleDevice,BleException exception) { } @Override public void onConnectSuccess(BleDevice bleDevice, BluetoothGatt gatt, int status) { } @Override public void onDisConnected(boolean isActiveDisConnected, BleDevice device, BluetoothGatt gatt, int status) { } }); #### - ### 取消扫描 `void cancelScan()` BleManager.getInstance().cancelScan(); Tips: —如果这个方法被调用，如果它仍然处于扫描状态，它将立即结束，并回调' onScanFinished '方法。 - ### 通知 `void notify(BleDevice bleDevice, String uuid_service, String uuid_notify, BleNotifyCallback callback)` `void notify(BleDevice bleDevice, String uuid_service, String uuid_notify, boolean useCharacteristicDescriptor, BleNotifyCallback callback)` BleManager.getInstance().notify( bleDevice, uuid_service, uuid_characteristic_notify, new BleNotifyCallback() { @Override public void onNotifySuccess() { } @Override public void onNotifyFailure(BleException exception) { } @Override public void onCharacteristicChanged(byte[] data) { } }); - ### 取消通知 `boolean stopNotify(BleDevice bleDevice, String uuid_service, String uuid_notify)` `boolean stopNotify(BleDevice bleDevice, String uuid_service, String uuid_notify, boolean useCharacteristicDescriptor)` BleManager.getInstance().stopNotify(uuid_service, uuid_characteristic_notify); - ### 表明 `void indicate(BleDevice bleDevice, String uuid_service, String uuid_indicate, BleIndicateCallback callback)` `void indicate(BleDevice bleDevice, String uuid_service, String uuid_indicate, boolean useCharacteristicDescriptor, BleIndicateCallback callback)` BleManager.getInstance().indicate( bleDevice, uuid_service, uuid_characteristic_indicate, new BleIndicateCallback() { @Override public void onIndicateSuccess() { } @Override public void onIndicateFailure(BleException exception) { } @Override public void onCharacteristicChanged(byte[] data) { } }); - ### 停止显示 `boolean stopIndicate(BleDevice bleDevice, String uuid_service, String uuid_indicate)` `boolean stopIndicate(BleDevice bleDevice, String uuid_service, String uuid_indicate, boolean useCharacteristicDescriptor)` BleManager.getInstance().stopIndicate(uuid_service, uuid_characteristic_indicate); - ### 写数据 `void write(BleDevice bleDevice, String uuid_service, String uuid_write, byte[] data, BleWriteCallback callback)` `void write(BleDevice bleDevice, String uuid_service, String uuid_write, byte[] data, boolean split, BleWriteCallback callback)` `void write(BleDevice bleDevice, String uuid_service, String uuid_write, byte[] data, boolean split, boolean sendNextWhenLastSuccess, long intervalBetweenTwoPackage, BleWriteCallback callback)` BleManager.getInstance().write( bleDevice, uuid_service, uuid_characteristic_write, data, new BleWriteCallback() { @Override public void onWriteSuccess(int current, int total, byte[] justWrite) { } @Override public void onWriteFailure(BleException exception) { } }); Tips: —如果需要发送大于20字节的长数据，则不需要扩展MTU，也不需要扩展MTU的无效。参数“boolean split”表示是否使用包传送;默认情况下，不带“boolean split”参数的“write”方法被分包到数据中超过20字节。 —在' onwritessuccess '回调方法上:' current '表示当前发送的数据包数量，' total '表示这次的数据包总数，' justWrite '表示刚刚发送成功的数据包。 - ### 读数据 `void read(BleDevice bleDevice, String uuid_service, String uuid_read, BleReadCallback callback)` BleManager.getInstance().read( bleDevice, uuid_service, uuid_characteristic_read, new BleReadCallback() { @Override public void onReadSuccess(byte[] data) { } @Override public void onReadFailure(BleException exception) { } }); - ### 获取 Rssi `void readRssi(BleDevice bleDevice, BleRssiCallback callback)` BleManager.getInstance().readRssi( bleDevice, new BleRssiCallback() { @Override public void onRssiFailure(BleException exception) { } @Override public void onRssiSuccess(int rssi) { } }); 小贴士: —获取设备的信号强度必须在设备连接完成后进行。 —有些设备可能因为超时而不能读取Rssi，不回调onrssissuccess()，或者回调onRssiFailure()。 - ### 设置Mtu `void setMtu(BleDevice bleDevice, int mtu, BleMtuChangedCallback callback)` BleManager.getInstance().setMtu(bleDevice, mtu, new BleMtuChangedCallback() { @Override public void onSetMTUFailure(BleException exception) { } @Override public void onMtuChanged(int mtu) { } }); Tips: —设置MTU需要在连接设备后进行操作。 —该方法的MTU设置为23，最大设置为512。 —并不是所有设备都支持MTU的扩展，MTU的扩展需要双方通信，也就是说，设备硬件的需要也支持MTU的扩展。调用此方法后，您可以通过onMtuChanged (int MTU)看到在最终设置后设备的最大传输单元被扩展到多少。如果设备不支持，无论多少设置，最终的MTU都是23。 - ### 连接优先级 `boolean requestConnectionPriority(BleDevice bleDevice,int connectionPriority)` Tips: - Request a specific connection priority. Must be one of{@link BluetoothGatt#CONNECTION_PRIORITY_BALANCED}, {@link BluetoothGatt#CONNECTION_PRIORITY_HIGH} or {@link BluetoothGatt#CONNECTION_PRIORITY_LOW_POWER}. - ### 设备切换 `BleDevice convertBleDevice(BluetoothDevice bluetoothDevice)` `BleDevice convertBleDevice(ScanResult scanResult)` Tips： - The completed BleDevice object is still unconnected, if necessary, advanced connection. - ### 获取所有连接的设备 `List getAllConnectedDevice()` BleManager.getInstance().getAllConnectedDevice(); - ### 获得一个连接设备的BluetoothGatt `BluetoothGatt getBluetoothGatt(BleDevice bleDevice)` - ### 获取连接设备的所有服务 `List getBluetoothGattServices(BleDevice bleDevice)` - ### 获取服务的所有特征 `List getBluetoothGattCharacteristics(BluetoothGattService service)` - ### 确定设备是否已连接 `boolean isConnected(BleDevice bleDevice)` BleManager.getInstance().isConnected(bleDevice); `boolean isConnected(String mac)` BleManager.getInstance().isConnected(mac); - ### 确定设备的当前连接状态 `int getConnectState(BleDevice bleDevice)` BleManager.getInstance().getConnectState(bleDevice); - ### 断开一个设备 `void disconnect(BleDevice bleDevice)` BleManager.getInstance().disconnect(bleDevice); - ### 断开所有设备 `void disconnectAllDevice()` BleManager.getInstance().disconnectAllDevice(); - ### 资源销毁 `void destroy()` BleManager.getInstance().destroy(); - ### HexUtil 数据操作工具类 `String formatHexString(byte[] data, boolean addSpace)` `byte[] hexStringToBytes(String hexString)` `char[] encodeHex(byte[] data, boolean toLowerCase)` ## BleDevice BLE设备对象是该框架中扫描、连接和操作的最小单位对象。 `String getName()` Bluetooth broadcast name `String getMac()` Bluetooth MAC `byte[] getScanRecord()` Broadcast data `int getRssi()` Initial signal intensity ## 版本迭代 版本号：1.0.0 支持与外围BLE设备进行扫描、连接、读、写、通知订阅与取消等基本操作 1. 初始化 2. 扫描 3. 连接 4. 取消扫描 5. 打开蓝牙 6. 关闭蓝牙 7. 读Characteristic 8. 写Characteristic 9. 打开Notify 10. 停止Notify 11. 设置Mtu ## 版权和许可信息 - Apache Licence