EasyBle

EasyBle is a framework used for android BLE, this framework makes android Ble operation simpler and supports basic BLE operations, besides, it also support batch writing data and multi connection

The version 1.0.x is no longer maintained , please use or update to the newest version(2.0.x)

中文文档

Gradle dependency

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

dependencies {
    implementation 'com.github.Ficat:EasyBle:v2.0.1'
}

Usage

The framework uses BleManager to manager BLE

1.Check if the device supports BLE and turn on bluetooth

        //check if the device supports BLE
        BleManager.supportBle(context);

        //is Bluetooth turned on?
        BleManager.isBluetoothOn();
        
        //If Bluetooth is turned off, you should call BleManager#enableBluetooth() to
        //turn on bluetooth with a request dialog, and you will receive the result from
        //the method onActivityResult() of this activity
        BleManager.enableBluetooth(activity,requestCode);

2.Get ble manager and initialization

        //scan/connection options is not necessary, if you don't set,
        //it will use default config
        BleManager.ScanOptions scanOptions = BleManager.ScanOptions
                .newInstance()
                .scanPeriod(10000)
                .scanDeviceName(null);

        BleManager.ConnectOptions connectOptions = BleManager.ConnectOptions
                .newInstance()
                .connectTimeout(12000);

        BleManager bleManager = BleManager
                        .getInstance()
                        .setScanOptions(scanOptions)//it is not necessary
                        .setConnectionOptions(connectOptions)//like scan options
                        .setLog(true, "TAG")
                        .init(this.getApplication());//Context is needed here,do not use Activity,which can cause Activity leak

3.Scan

If sdk version >=23, scanning must have location permission，if Android version sdk version >=29(Android10), scanning must have fine location permission(Manifest.permission.ACCESS_FINE_LOCATION)

        bleManager.startScan(new BleScanCallback() {
            @Override
            public void onLeScan(BleDevice device, int rssi, byte[] scanRecord) {
                String name = device.name;
                String address = device.address;
            }

            @Override
            public void onStart(boolean startScanSuccess, String info) {
                if (startScanSuccess) {
                    //start scan successfully
                } else {
                    //fail to start scan, you can see details from 'info'
                    String failReason = info;
                }
            }

            @Override
            public void onFinish() {
               
            }
        });

        //start scan with specified scanOptions
        bleManager.startScan(scanOptions, bleScanCallback);

Once target remote device has been discovered you can use stopScan() to stop scanning

        bleManager.stopScan();

4.Connect

You can connect to remote device by device address or BleDevice object

       BleConnectCallback bleConnectCallback = new BleConnectCallback() {
            @Override
            public void onStart(boolean startConnectSuccess, String info, BleDevice device) {
                if (startConnectSuccess) {
                    //start to connect successfully
                } else {
                    //fail to start connection, see details from 'info'
                    String failReason = info;
                }
            }

            @Override
            public void onFailure(int failCode, String info, BleDevice device) {
                if(failCode == BleConnectCallback.FAIL_CONNECT_TIMEOUT){
                    //connection timeout
                }else{
                    //connection fail due to other reasons
                }

            }

             @Override
             public void onConnected(BleDevice device) {

             }

             @Override
             public void onDisconnected(String info, int status, BleDevice device) {

             }
        };

       bleManager.connect(bleDevice, bleConnectCallback);
       //connect with specified connectOptions
       bleManager.connect(bleDevice, connectOptions, bleConnectCallback);

       //connect with mac address
       bleManager.connect(address, bleConnectCallback);
       bleManager.connect(address, connectOptions, bleConnectCallback);

Use one of the following methods to disconnect from remote device

       //disconnect from the specific remote device by BleDevice object
       bleManager.disconnect(bleDevice);
	   
       //disconnect from the specific remote device by address
       bleManager.disconnect(address);

       //disconnect all connected devices
       bleManager.disconnectAll();

5.Notify

Both notification and indication use the following method to set notification or indication

       bleManager.notify(bleDevice, serviceUuid, notifyUuid, new BleNotifyCallback() {
            @Override
            public void onCharacteristicChanged(byte[] data, BleDevice device) {
              
            }

            @Override
            public void onNotifySuccess(String notifySuccessUuid, BleDevice device) {

            }

            @Override
            public void onFailure(int failCode, String info, BleDevice device) {
                switch (failCode) {
                    case BleCallback.FAIL_DISCONNECTED://connection has disconnected
                        break;
                    case BleCallback.FAIL_OTHER://other reason
                        break;
                    default:
                        break;
                }

            }
        });

When you want to cancel notification or indication, you can call cancelNotify()

       bleManager.cancelNotify(bleDevice, notifyUuid);

6.Write

       bleManager.write(bleDevice, serviceUuid, writeUuid, data, new BleWriteCallback() {
            @Override
            public void onWriteSuccess(byte[] data, BleDevice device) {

            }

            @Override
            public void onFailure(int failCode, String info, BleDevice device) {

            }
        });

if the length of the data you wanna deliver to remote device is larger than MTU(default 20), you can use the following method to write by batch

       bleManager.writeByBatch(bleDevice, serviceUuid, writeUuid, data, lengthPerPackage, new  BleWriteByBatchCallback() {
            @Override
            public void writeByBatchSuccess(byte[] data, BleDevice device) {

            }

            @Override
            public void onFailure(int failCode, String info, BleDevice device) {

            }
        });

7.Destroy

You must call destroy() to release some resources after BLE communication end

       bleManager.destroy();

Other api

License

Copyright 2018 Ficat

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.