# EasyBle

**Repository Path**: sscl/easy-ble

## Basic Information

- **Project Name**: EasyBle
- **Description**: 一个android 的通用BLE（Bluetooth Low Energy）库。
包含对蓝牙BLE设备的搜索（封装类：BleScanner） 连接（封装类：BleConnector）
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2024-02-06
- **Last Updated**: 2024-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyBle

#### 介绍
一个android 的通用BLE（Bluetooth Low Energy）库。
包含对蓝牙BLE设备的搜索（封装类：BleScanner）与连接（封装类：BleConnector）

#### 软件架构
软件架构说明

当前最新版本号：[![](https://jitpack.io/v/com.gitee.sscl/easy-ble.svg)](https://jitpack.io/#com.gitee.sscl/easy-ble)

# 配置：(Configure)

## 1.直接将library依赖到项目


## 2.gradle配置依赖


```xml
allprojects {
	repositories {
		...
		maven { url 'https://jitpack.io' }
	}
}
```

```xml
dependencies {
        //注意 TAG为版本号
        implementation 'com.gitee.sscl:easy-ble:Tag'
}
```

## 3. gradle.kts配置依赖


```xml
allprojects {
	repositories {
		...
		 maven { url = URI("https://jitpack.io") }
	}
}
```

```xml
dependencies {
        //注意 TAG为版本号
        implementation("com.gitee.sscl:easy-ble:Tag")
}
```


# 使用说明

## 蓝牙功能基本判断

```kotlin


 //开启log
 BleManager.enableLog(true)
 //设置log打印等级
 BleManager.setLogLevel(LogLevel.DEBUG)

 if (!BleManager.supportBluetooth()) {
     ToastUtil.toastLong(this@MainActivity, "设备不支持蓝牙")
     return@OnClickListener
 }
 if (!BleManager.supportBluetoothLe()) {
     ToastUtil.toastLong(this@MainActivity, "设备不支持蓝牙BLE")
     return@OnClickListener
 }
 if (!BleManager.isBlueEnable()) {
     BleManager.enableBluetooth()
     return@OnClickListener
 }

```

## 蓝牙搜索

```kotlin

 //设置回调后直接使用
 BleManager.getScannerInstance()
            .setOnBleScanListener(onBleScanListener)
            .startScan()

 //使用自定义搜索参数
 BleManager.getScannerInstance()
            .setOnBleScanListener(onBleScanListener)
            .setBleScanMode(scanMode)
            .setBleCallbackType(callbackType)
            .setBleScanPhy(scanPhy)
            .setLegacy(false)
            .setBleMatchMode(matchMode)
            .setReportDelay(0)
            .setScanTimeout(10,TimeUnit.SECCONDS)
            .setBleNumOfMatches(numOfMatches)
            .startScan()
```

```kotlin
//添加搜索过滤条件
BleManager.getScannerInstance().addFilterFullName("name")
BleManager.getScannerInstance().addFilterFullName(arrayListOf("name1", "name2"))
BleManager.getScannerInstance().addFilterFullAddress("address")
BleManager.getScannerInstance().addFilterFullAddress(arrayListOf("address1", "address2"))
BleManager.getScannerInstance().addFilterUuid("uuidString")
BleManager.getScannerInstance().addFilterUuid(arrayListOf("uuidString1", "uuidString2"))
val scanFilter = ScanFilter.Builder()
    .setDeviceName("name")
    .setDeviceAddress("address")
    .setServiceUuid(ParcelUuid(UUID.fromString("uuidString")))
    .build()
BleManager.getScannerInstance().addCustomFilter(scanFilter)
...还有更多过滤条件，此处不再一一举例
```

```kotlin
//移除或清空过滤条件
BleManager.getScannerInstance().removeFilterFullAddress("address")
BleManager.getScannerInstance().removeFilterFullName("name")
...还有更多移除过滤条件的方法，此处不再一一举例

BleManager.getScannerInstance().clearFilterFullName()
BleManager.getScannerInstance().clearFilterFullAddress()
...还有更多清空过滤条件的方法，此处不再一一举例
```

## 蓝牙连接

###### 下方示例代码都以传入device举例，也可以直接传入蓝牙设备的完整MAC地址进行连接，连接结果在onBleConnectStateChangedListener回调中
##### 注意：直接传入蓝牙设备的完整MAC地址进行连接时，请保证至少进行过1次搜索并且搜索到了该设备，否则大概率会连接超时或失败，原因尚未深究

```kotlin
//连接设备
val succeed = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    BleManager.getConnectorInstance().connectDevice(
        scanResult.device,
        onBleConnectStateChangedListener,
        singleConnectActivityViewModel.autoReconnect.value ?: DEFAULT_RECONNECT,
        singleConnectActivityViewModel.bleConnectTransport.value
            ?: DEFAULT_BLE_CONNECT_TRANSPORT,
        singleConnectActivityViewModel.bleConnectPhyMask.value
            ?: DEFAULT_BLE_CONNECT_PHY_MASK
    )
} else if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    BleManager.getConnectorInstance().connectDevice(
        scanResult.device,
        onBleConnectStateChangedListener,
        singleConnectActivityViewModel.autoReconnect.value ?: DEFAULT_RECONNECT,
        singleConnectActivityViewModel.bleConnectTransport.value
            ?: DEFAULT_BLE_CONNECT_TRANSPORT
    )
} else {
    BleManager.getConnectorInstance().connectDevice(
        scanResult.device,
        onBleConnectStateChangedListener,
        singleConnectActivityViewModel.autoReconnect.value ?: DEFAULT_RECONNECT
    )
}
if (succeed) {
    showConnecting()
    binding.circlePointView.setColor(Color.YELLOW)
}else {
    //TODO 连接发起失败，具体原因需要看系统日志信息
|
```

```kotlin
//设置数据操作回调，并不需要全部设置，根据使用场景设置所需的回调即可
 val connector = BleManager.getConnectorInstance()
            .setOnDescriptorDataOptionListener(device, onDescriptorDataOptionListener)
            .setOnCharacteristicDataOptionsListener(device, onCharacteristicDataOptionsListener)
            .setonReadRemoteRssiListener(device, onReadRemoteRssiListener)
            .setOnMtuChangedListener(device, onMtuChangedListener)
            .setOnReliableWriteCompletedListener(device, onReliableWriteCompletedListener)
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            connector.setOnPhyOptionsListener(device, onPhyOptionsListener)
        }
```

```kotlin
//写入描述数据
val succeed = BleManager.getConnectorInstance().writeCompatDescriptorData(
                    device,
                    descriptor,
                    byteArray
                )
```

```kotlin
//写入特征数据
val succeed = BleManager.getConnectorInstance().writeCompatCharacteristicData(
                    device,
                    characteristic,
                    byteArray
                )

```

##### 还有更多数据操作与回调此处不再一一举例，在开发工具中都能快速提示出来


#### 支持多设备连接，具体能连接多少个设备因硬件条件不同而有所区别，我测试过的所有设备中，最多的能连接6个（但是连接极其不稳定，根本无法使用），大多数的都能连接3。4个且稳定，极少数的不支持多设备同时连接（硬件配置奇差的那种）


#### 安装教程

1.  xxxx
2.  xxxx
3.  xxxx

#### 使用说明

1.  xxxx
2.  xxxx
3.  xxxx

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)