EasyBle

EasyBle is a framework used for android BLE, it makes android Ble operation simpler and supports basic BLE operations

On android12 or higher devices, BLE requires some permissions, please use or update it to the newest version(3.2.x)

中文文档

Gradle dependency

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

dependencies {
    implementation 'com.github.Ficat:EasyBle:v3.2.0'
}

Usage

The framework uses BleManager to manager BLE

1.Check if the device supports BLE, request BLE required permissions and turn on bluetooth.<br>

See BLE permission details

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

        // Request BLE permissions. On Android 12 or higher devices, most BLE operations such
        // as enabling Bluetooth, notifications, and write/read require these permissions, so
        // this step is necessary. You can get all BLE permissions by BleManager#getBleRequiredPermissions().
        List<String> permissions = BleManager.getBleRequiredPermissions();
        if (list.size() > 0) { // Lower version may not require any permissions
            requestPermissions(permissions);
        }

        // Is Bluetooth turned on?
        BleManager.isBluetoothOn();
        
        // If Bluetooth is turned off, you can call BleManager#enableBluetooth() to turn on
        // bluetooth with a request dialog, and you will receive the result from the method
        // onActivityResult() of this activity. Note that the method requires BLE permissions,
        // so do not forget to request it and ensure all permissions have been granted.
        boolean requestStart = BleManager.enableBluetooth(activity,requestCode);
        if(!requestStart) {
            // No BLE permissions or not support BLE
        }

2.Get ble manager and initialization

        // Scan or connection option is not necessary, if you don't set, The default
        // configuration will be applied
        BleManager.ScanOptions scanOptions = BleManager.ScanOptions
                .newInstance()
                .scanPeriod(10000)// scan timeout
                .scanDeviceName(null);

        BleManager.ConnectionOptions connOptions = BleManager.ConnectionOptions
                .newInstance()
                .connectionPeriod(12000);// connection timeout

        BleManager bleManager = BleManager
                        .getInstance()
                        .setScanOptions(scanOptions)
                        .setConnectionOptions(connOptions)
                        .setLog(true, "TAG")
                        .init(this.getApplication());// Init() requires context, to avoid memory leak, you'd better use Application instance

3.Scan

On API23+ or higher devices, scan requires some permissions, so ensure all BLE permissions have been granted. How to use BleDevice to carry extra info.

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

            @Override
            public void onScanStarted() {

            }

            @Override
            public void onScanFinished() {

            }

            @Override
            public void onScanFailed(int code) {
                switch (code) {
                    case BleErrorCodes.BLUETOOTH_OFF:
                        // Bluetooth turned off
                        break;
                    case BleErrorCodes.SCAN_PERMISSION_NOT_GRANTED:
                        // Scan permissions not granted
                        break;
                    case BleErrorCodes.SCAN_ALREADY_STARTED:
                        // Previous scan not finished
                        break;
                    case BleErrorCodes.SCAN_TOO_FREQUENTLY:
                        // Scan too frequently
                        break;
                    case BleErrorCodes.UNKNOWN:
                        // Failed to start scan because of unknown reason
                        break;
                }
            }
        });

        // 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. Like scan, now connection also requires permissions.<br> Note: Android versions below 10 allow only one connection request at a time and queue all subsequent requests. In Android 10 and higher, the system groups connection requests for batched execution. That means, if Android versions below 10, we must wait for a callback for a previous connection before we initiate a new connection request

       BleConnectCallback bleConnectCallback = new BleConnectCallback() {
            @Override
            public void onConnectionStarted(BleDevice device) {

            }

            @Override
            public void onConnected(BleDevice device) {

            }

            @Override
            public void onDisconnected(BleDevice device, int gattOperationStatus) {

            }

            @Override
            public void onConnectionFailed(int errCode, BleDevice device) {
                switch (errCode) {
                    case BleErrorCodes.BLUETOOTH_OFF:
                        // Bluetooth turned off
                        break;
                    case BleErrorCodes.CONNECTION_PERMISSION_NOT_GRANTED:
                        // Connection permissions not granted
                        break;
                    case BleErrorCodes.CONNECTION_REACH_MAX_NUM:
                        // Max connection num reached
                        break;
                    case BleErrorCodes.CONNECTION_TIMEOUT:
                        // Connection timed out
                        break;
                    case BleErrorCodes.CONNECTION_CANCELED:
                        // Connection canceled
                        break;
                    case BleErrorCodes.CONNECTION_ALREADY_STARTED_OR_ESTABLISHED:
                        // Connection already started or established
                        break;
                    case BleErrorCodes.UNKNOWN:
                        // Unknown
                        break
                    default:
                        break;
                }
            }
        };

       bleManager.connect(bleDevice, bleConnectCallback);

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

       // Second param:  Select a specified connection option
       bleManager.connect(bleDevice, connectionOptions, connectCallback);

Call one of the following methods to disconnect from remote device

       // Disconnect from the remote device by BleDevice object
       bleManager.disconnect(bleDevice);
	   
       // Disconnect from the 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[] receivedData, UUID characteristicUuid, BleDevice device) {
                // Note that this is called from a non-UI thread
            }

            @Override
            public void onNotifySuccess(UUID characteristicUuid, BleDevice device) {

            }

            @Override
            public void onNotifyFailed(int errorCode, UUID characteristicUuid, BleDevice device) {
                switch (errorCode) {
                    case BleErrorCodes.CONNECTION_NOT_ESTABLISHED:
                        // Connection not established yet
                        break;
                    case BleErrorCodes.SERVICE_NOT_FOUND:
                        // Service not found in the remote device
                        break;
                    case BleErrorCodes.CHARACTERISTIC_NOT_FOUND_IN_SERVICE:
                        // Characteristic not found in specified service
                        break;
                    case BleErrorCodes.NOTIFICATION_OR_INDICATION_UNSUPPORTED:
                        // Characteristic not support notification or indication
                        break;
                    case BleErrorCodes.UNKNOWN:
                        // Unknown
                        break;
                }
            }
        });

Call cancelNotify() to cancel notification or indication

       bleManager.cancelNotify(bleDevice, notifyUuid);

6.Write

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

            }

            @Override
            public void onWriteFailed(int errCode, byte[] data, UUID characteristicUuid, BleDevice device) {
                switch (errCode) {
                    case BleErrorCodes.CONNECTION_NOT_ESTABLISHED:
                        // Connection not established yet
                        break;
                    case BleErrorCodes.SERVICE_NOT_FOUND:
                        // Service not found in the remote device
                        break;
                    case BleErrorCodes.CHARACTERISTIC_NOT_FOUND_IN_SERVICE:
                        // Characteristic not found in specified service
                        break;
                    case BleErrorCodes.WRITE_UNSUPPORTED: