easyble-x: A simple framework for Android Bluetooth Low Energy (BLE)

原作者: [db:作者] 来自: 网络收藏邀请

开源软件名称：

easyble-x

开源软件地址：

https://gitee.com/fszeng/easyble-x

开源软件介绍：

Android BLE开发框架

基于此库编写的BLE调试助手——BLE调试宝，各大应用市场都已上架，欢迎下载使用。

功能

支持多设备同时连接
支持广播包解析
支持连接同时配对
支持搜索系统已连接设备
支持搜索器设置
支持自定义搜索过滤条件
支持自动重连、最大重连次数限制、直接重连或搜索到设备再重连控制
支持请求延时及发送延时设置
支持分包大小设置、最大传输单元设置
支持观察者监听或回调方式。注意：观察者监听和回调只能取其一！
支持使用注解@RunOn控制回调线程
支持设置回调或观察者的方法默认执行线程
支持发送设置（是否等待发送结果回调再发送下一包）
支持写入模式设置
支持设置连接的传输方式
支持连接超时设置

配置

因为使用了jdk8的一些特性，需要在module的build.gradle里添加如下配置：

//纯java的项目android {	compileOptions {		sourceCompatibility JavaVersion.VERSION_1_8		targetCompatibility JavaVersion.VERSION_1_8	}}//有kotlin的项目还需要在project的build.gradle里添加allprojects {    tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).all {        sourceCompatibility = JavaVersion.VERSION_1_8        targetCompatibility = JavaVersion.VERSION_1_8        kotlinOptions {            jvmTarget = '1.8'        }    }}

module的build.gradle中的添加依赖，自行将latestVersion修改为最新版本，同步后通常就可以用了：

dependencies {	...	implementation 'cn.wandersnail:easyble-x:latestVersion'	implementation 'cn.wandersnail:commons-android:latestVersion'}

如果从jcenter下载失败。在project的build.gradle里的repositories添加内容，最好两个都加上，添加完再次同步即可。

allprojects {	repositories {		...		mavenCentral()		maven { url 'https://jitpack.io' }	}}

使用方法

初始化SDK

实例化有两种方式：

使用默认方式自动构建实例，直接获取实例即可

//实例化并初始化EasyBLE.getInstance().initialize(this);

构建自定义实例，必须在EasyBLE.getInstance()之前！！

ScanConfiguration scanConfig = new ScanConfiguration()		.setScanSettings(new ScanSettings.Builder()				.setScanMode(ScanSettings.SCAN_MODE_BALANCED)//搜索模式				.build())		.setScanPeriodMillis(15000)//搜索周期		.setAcceptSysConnectedDevice(true)//是否将系统蓝牙已连接的设备放到搜索结果中		.setOnlyAcceptBleDevice(true);//是否过滤非ble设备EasyBLE ble = EasyBLE.getBuilder().setScanConfiguration(scanConfig)        .setScannerType(ScannerType.LE)//指定蓝牙扫描器，默认为系统Android5.0以上使用ScannerType.LE        .setExecutorService(executorService)//自定义线程池用来执行后台任务，也可使用默认        .setDeviceCreator(creator)//设备实例构建器。返回搜索结果时的设备对象由此构建器实例化		.setObserveAnnotationRequired(false)//不强制使用{@link Observe}注解才会收到被观察者的消息，默认为false		.setMethodDefaultThreadMode(ThreadMode.MAIN)//指定回调方法和观察者方法的默认线程，默认为ThreadMode.MAIN		.build();ble.initialize(this);

销毁SDK

//如果中途需要修改配置重新实例化，调用此方法后即可重新构建EasyBLE实例EasyBLE.getInstance().destroy();

日志输出控制

EasyBLE.getInstance().setLogEnabled(true);//开启日志打印

蓝牙搜索

定义搜索监听器
Android6.0以上搜索需要至少模糊定位权限，如果targetSdkVersion设置29以上需要精确定位权限。权限需要动态申请

private ScanListener scanListener = new ScanListener() {	@Override	public void onScanStart() {		//搜索开始	}	@Override	public void onScanStop() {		//搜索停止	}    /**     * 搜索到BLE设备     *     * @param device           搜索到的设备     * @param isConnectedBySys 是否已被系统蓝牙连接上     */	@Override	public void onScanResult(@NonNull Device device, boolean isConnectedBySys) {		//搜索结果	}	@Override	public void onScanError(int errorCode, @NotNull String errorMsg) {		switch(errorCode) {			case ScanListener.ERROR_LACK_LOCATION_PERMISSION://缺少定位权限						break;			case ScanListener.ERROR_LOCATION_SERVICE_CLOSED://位置服务未开启						break;			case ScanListener.ERROR_SCAN_FAILED://搜索失败				break;		}	}};

添加监听

EasyBLE.getInstance().addScanListener(scanListener);

开始搜索

EasyBLE.getInstance().startScan();

停止搜索

EasyBLE.getInstance().stopScan();

停止监听

EasyBLE.getInstance().removeScanListener(scanListener);

观察者模式数据及事件

定义观察者。实现EventObserver接口即可：

public class MainActivity extends AppCompatActivity implements EventObserver {    /**     * 使用{@link Observe}确定要接收消息，{@link RunOn}指定在主线程执行方法，设置{@link Tag}防混淆后找不到方法     */    @Tag("onConnectionStateChanged")     @Observe    @RunOn(ThreadMode.MAIN)    @Override    public void onConnectionStateChanged(@NonNull Device device) {        switch (device.getConnectionState()) {            case SCANNING_FOR_RECONNECTION:                break;            case CONNECTING:                break;            case DISCONNECTED:                break;            case SERVICE_DISCOVERED:                break;        }    }	    /**     * 使用{@link Observe}确定要接收消息，方法在{@link EasyBLEBuilder#setMethodDefaultThreadMode(ThreadMode)}指定的线程执行     */    @Observe    @Override    public void onNotificationChanged(@NonNull Request request, boolean isEnabled) {        if (request.getType() == RequestType.SET_NOTIFICATION) {            if (isEnabled) {                Log.d("EasyBLE", "通知开启了");            } else {                Log.d("EasyBLE", "通知关闭了");            }        } else {            if (isEnabled) {                Log.d("EasyBLE", "Indication开启了");            } else {                Log.d("EasyBLE", "Indication关闭了");            }        }    }    /**     * 如果{@link EasyBLEBuilder#setObserveAnnotationRequired(boolean)}设置为false时，无论加不加{@link Observe}注解都会收到消息。     * 设置为true时，必须加{@link Observe}才会收到消息。     * 默认为false，方法默认执行线程在{@link EasyBLEBuilder#setMethodDefaultThreadMode(ThreadMode)}指定     */    @Override    public void onCharacteristicWrite(@NonNull Request request, @NonNull byte[] value) {        Log.d("EasyBLE", "成功写入：" + StringUtils.toHex(value, " "));    }}

注册观察者

EasyBLE.getInstance().registerObserver(observer);

取消注册观察者

EasyBLE.getInstance().unregisterObserver(observer);

连接

连接配置

//连接配置，举个例随意配置两项ConnectionConfiguration config = new ConnectionConfiguration();config.setConnectTimeoutMillis(10000);config.setRequestTimeoutMillis(1000);

建立连接

connection = EasyBLE.getInstance().connect(device, config);//观察者监听连接状态

断开连接，还可重连

EasyBLE.getInstance().disconnectConnection(device);//断开指定连接//EasyBLE.getInstance().disconnectAllConnections();//断开所有连接

释放连接，不可重连，需要重新建立连接

EasyBLE.getInstance().releaseConnection(device);//释放指定连接//EasyBLE.getInstance().releaseAllConnections();//释放所有连接

读写特征值、开启Notify

两种方式：

接口回调方式

//开关通知boolean isEnabled = connection.isNotificationOrIndicationEnabled(serviceUuid, characteristicUuid);Request.Builder<NotificationChangeCallback> builder = Request.getSetNotificationBuilder(serviceUuid, characteristicUuid, !isEnabled);//不设置回调，使用观察者模式接收结果builder.build().execute(connection);//读取特征值Request.Builder<ReadCharacteristicCallback> builder = Request.getReadCharacteristicBuilder(serviceUuid, characteristicUuid);builder.setTag(UUID.randomUUID().toString());builder.setPriority(Integer.MAX_VALUE);//设置请求优先级//设置了回调则观察者不会收到此次请求的结果消息builder.setCallback(new ReadCharacteristicCallback() {	//注解可以指定回调线程	@RunOn(ThreadMode.BACKGROUND)	@Override	public void onCharacteristicRead(@NonNull Request request, @NonNull byte[] value) {		Log.d("EasyBLE", "主线程：" + (Looper.getMainLooper() == Looper.myLooper()));		Log.d("EasyBLE", "读取到特征值：" + StringUtils.toHex(value, " "));	}	//不使用注解指定线程的话，使用构建器设置的默认线程	@Override	public void onRequestFailed(@NonNull Request request, int failType, @Nullable Object value) {	}});builder.build().execute(connection);//写特征值Request.WriteCharacteristicBuilder builder = Request.getWriteCharacteristicBuilder(serviceUuid, characteristicUuid, "test write".getBytes());//根据需要设置写入配置builder.setWriteOptions(new WriteOptions.Builder()		.setPackageSize(20)		.setPackageWriteDelayMillis(5)		.setRequestWriteDelayMillis(10)		.setWaitWriteResult(true)		.setWriteType(BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT)		.build());//不设置回调，使用观察者模式接收结果connection.execute(builder.build());

使用观察者模式接收结果。不在请求构建器中设置回调即可

释放SDK，释放后必须重新初始化后方可使用

EasyBLE.getInstance().release();

代码混淆

如果使用jar方式依赖，需要添加一下混淆规则。使用aar或直接远程依赖不需要额外添加，库里自带混淆规则

-keep class * implements cn.wandersnail.commons.observer.Observe {	public <methods>;}-keep class * implements cn.wandersnail.ble.Request {    !private *;}