easyble2

A framework for Android Bluetooth Low Energy (BLE)

License

License

GroupId

GroupId

com.github.wandersnail
ArtifactId

ArtifactId

easyble2
Last Version

Last Version

1.1.4
Release Date

Release Date

Type

Type

aar
Description

Description

easyble2
A framework for Android Bluetooth Low Energy (BLE)
Project URL

Project URL

https://github.com/wandersnail
Source Code Management

Source Code Management

https://github.com/wandersnail/easyble2

Download easyble2

How to add to project

<!-- https://jarcasting.com/artifacts/com.github.wandersnail/easyble2/ -->
<dependency>
    <groupId>com.github.wandersnail</groupId>
    <artifactId>easyble2</artifactId>
    <version>1.1.4</version>
    <type>aar</type>
</dependency>
// https://jarcasting.com/artifacts/com.github.wandersnail/easyble2/
implementation 'com.github.wandersnail:easyble2:1.1.4'
// https://jarcasting.com/artifacts/com.github.wandersnail/easyble2/
implementation ("com.github.wandersnail:easyble2:1.1.4")
'com.github.wandersnail:easyble2:aar:1.1.4'
<dependency org="com.github.wandersnail" name="easyble2" rev="1.1.4">
  <artifact name="easyble2" type="aar" />
</dependency>
@Grapes(
@Grab(group='com.github.wandersnail', module='easyble2', version='1.1.4')
)
libraryDependencies += "com.github.wandersnail" % "easyble2" % "1.1.4"
[com.github.wandersnail/easyble2 "1.1.4"]

Dependencies

There are no dependencies for this project. It is a standalone project that does not depend on any other jars.

Project Modules

There are no modules declared in this project.

Android BLE开发框架

基于此库编写的BLE调试助手——BLE调试宝,各大应用市场都已上架,欢迎下载使用。下面放两个常用的应用市场地址

第一次进入是主页的话,重新再进一次就是应用详情页了

最新版本

Maven Central Release

功能

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

配置

  1. 因为使用了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'
            apiVersion = '1.3'
            languageVersion = '1.3'
        }
    }
}
  1. module的build.gradle中的添加依赖,自行修改为最新版本,同步后通常就可以用了:
dependencies {
	...
	implementation 'cn.wandersnail:easyble-x:latestVersion'
	implementation 'cn.wandersnail:commons-android:latestVersion'
}
  1. 如果从jcenter下载失败。在project的build.gradle里的repositories添加内容,最好两个都加上,添加完再次同步即可。
allprojects {
	repositories {
		...
		mavenCentral()
		maven { url 'https://jitpack.io' }
	}
}

使用方法

初始化SDK

实例化有两种方式:

  1. 使用默认方式自动构建实例,直接获取实例即可
//实例化并初始化
EasyBLE.getInstance().initialize(this);
  1. 构建自定义实例,必须在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}注解才会收到被观察者的消息,强制使用的话,性能会好一些
		.setMethodDefaultThreadMode(ThreadMode.MAIN)//指定回调方法和观察者方法的默认线程
		.build();
ble.initialize(this);

销毁SDK

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

日志输出控制

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

蓝牙搜索

  1. 定义搜索监听器

    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;
		}
	}
};
  1. 添加监听
EasyBLE.getInstance().addScanListener(scanListener);
  1. 开始搜索
EasyBLE.getInstance().startScan();
  1. 停止搜索
EasyBLE.getInstance().stopScan();
  1. 停止监听
EasyBLE.getInstance().removeScanListener(scanListener);

观察者模式数据及事件

  1. 定义观察者。实现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, " "));
    }
}
  1. 注册观察者
EasyBLE.getInstance().registerObserver(observer);
  1. 取消注册观察者
EasyBLE.getInstance().unregisterObserver(observer);

连接

  1. 连接配置
//连接配置,举个例随意配置两项
ConnectionConfiguration config = new ConnectionConfiguration();
config.setConnectTimeoutMillis(10000);
config.setRequestTimeoutMillis(1000);
  1. 建立连接
connection = EasyBLE.getInstance().connect(device, config);//观察者监听连接状态
  1. 断开连接,还可重连
EasyBLE.getInstance().disconnectConnection(device);//断开指定连接
//EasyBLE.getInstance().disconnectAllConnections();//断开所有连接
  1. 释放连接,不可重连,需要重新建立连接
EasyBLE.getInstance().releaseConnection(device);//释放指定连接
//EasyBLE.getInstance().releaseAllConnections();//释放所有连接

读写特征值、开启Notify

两种方式:

  1. 接口回调方式
//开关通知
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());
  1. 使用观察者模式接收结果。不在请求构建器中设置回调即可

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

EasyBLE.getInstance().release();

代码混淆

-keep class * implements cn.wandersnail.commons.observer.Observe {
	public <methods>;
}
#保持 Serializable 不被混淆
-keep class * implements cn.wandersnail.ble.Request {
    !private *;
}

Demo效果预览

image image image

Versions

Version
1.1.4
1.1.3
1.1.2
1.1.1
1.0.1
1.0.0