Android Bluetooth Low Energy (BLE)簡單方便的藍牙開源庫——EasyBLE

源碼傳送門

最新版本

功能

• 支持多設備同時連接
• 支持廣播包解析
• 支持連接同時配對
• 支持搜索系統已連接設備
• 支持搜索器設置
• 支持自定義搜索過濾條件
• 支持自動重連、最大重連次數限制、直接重連或搜索到設備再重連控制
• 支持請求延時及發送延時設置
• 支持分包大小設置、最大傳輸單元設置
• 支持觀察者監聽或回調方式。注意：觀察者監聽和回調只能取其一！
• 支持使用注解@RunOn控制回調線程，使用注解@Observe控制觀察者的方法執行線程
• 支持設置回調或觀察者的方法默認執行線程
• 支持發送設置（是否等待發送結果回調再發送下一包）
• 支持寫入模式設置
• 支持設置連接的傳輸方式
• 支持連接超時設置

配置

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'
        }
    }
}

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

dependencies {
	...
	implementation 'cn.wandersnail:easyble-x:latestVersion'
	//額外三個依賴
	implementation 'cn.wandersnail:common-utils:latestVersion'
	implementation 'cn.wandersnail:common-observer:latestVersion'
	implementation 'cn.wandersnail:common-poster:latestVersion'
	//也可以使用
	//implementation 'cn.wandersnail:common-full:latestVersion'//此依賴包含上面三個
}

3. 如果從jcenter下載失敗。在project的build.gradle里的repositories添加內容，最好兩個都加上，添加完再次同步即可。

allprojects {
	repositories {
		...
		mavenCentral()
		maven { url 'https://dl.bintray.com/wandersnail/androidx/' }
	}
}

使用方法

初始化SDK

實例化有兩種方式：

1. 使用默認方式自動構建實例，直接獲取實例即可

//實例化並初始化
EasyBLE.getInstance().initialize(this);

2. 構建自定義實例，必須在EasyBLE.getInstance()之前！！

ScanConfiguration scanConfig = new ScanConfiguration()
		.setScanSettings(new ScanSettings.Builder()
				.setScanMode(ScanSettings.SCAN_MODE_BALANCED)
				.build())
		.setScanPeriodMillis(15000)
		.setAcceptSysConnectedDevice(true)
		.setOnlyAcceptBleDevice(true);
EasyBLE ble = EasyBLE.getBuilder().setScanConfiguration(scanConfig)
		.setObserveAnnotationRequired(false)//不強制使用{@link Observe}注解才會收到被觀察者的消息，強制使用的話，性能會好一些
		.setMethodDefaultThreadMode(ThreadMode.MAIN)//指定回調方法和觀察者方法的默認線程
		.build();
ble.initialize(this);

銷毀SDK

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

日志輸出控制

EasyBLE.getInstance().setLogEnabled(true);//開啟日志打印

藍牙搜索

1. 定義搜索監聽器

private ScanListener scanListener = new ScanListener() {
	@Override
	public void onScanStart() {
		//搜索開始
	}

	@Override
	public void onScanStop() {
		//搜索停止
	}

	@Override
	public void onScanResult(@NotNull Device device) {
		//搜索結果
	}

	@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;
		}
	}
};

2. 添加監聽

EasyBLE.getInstance().addScanListener(scanListener);

3. 開始搜索

EasyBLE.getInstance().startScan();

4. 停止搜索

EasyBLE.getInstance().stopScan();

5. 停止監聽

EasyBLE.getInstance().removeScanListener(scanListener);

觀察者模式數據及事件

1. 定義觀察者。實現EventObserver接口即可：

public class MainActivity extends AppCompatActivity implements EventObserver {
    /**
     * 使用{@link Observe}確定要接收消息，並在主線程執行方法
     */
    @Observe(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, " "));
    }
}

2. 注冊觀察者

EasyBLE.getInstance().registerObserver(observer);

3. 取消注冊觀察者

EasyBLE.getInstance().unregisterObserver(observer);

連接

1. 連接配置

//連接配置，舉個例隨意配置兩項
ConnectionConfiguration config = new ConnectionConfiguration();
config.setConnectTimeoutMillis(10000);
config.setRequestTimeoutMillis(1000);

2. 建立連接

connection = EasyBLE.getInstance().connect(device, config);//觀察者監聽連接狀態

3. 斷開連接，還可重連

EasyBLE.getInstance().disconnectConnection(device);//斷開指定連接
//EasyBLE.getInstance().disconnectAllConnections();//斷開所有連接

4. 釋放連接，不可重連，需要重新建立連接

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());

2. 使用觀察者模式接收結果。不在請求構建器中設置回調即可

釋放SDK，釋放后必須重新初始化后方可使用

EasyBLE.getInstance().release();

Demo效果預覽

基於此庫的BLE調試app