Android Bluetooth Low Energy (BLE) Example

As you might be aware, Bluetooth technology has been one of the most used technology when a connection has to be established with a remote device. But this technology also has a major limitation, i.e. high battery consumption. Therefore an improved version of this technology with low energy consumption was introduced, called BLE (Bluetooth Low Energy). Therefore also on Android Bluetooth Low Energy was introduced with API 18 (Android 4.3). This opened up a whole new dimension in the world of Android development. All sorts of new hardware devices were introduced in the market, with compliance to Bluetooth low energy standard, like heart rate monitors, fitness devices and many more. Since this Android Bluetooth low energy API is a little new. Till now there is no proper code example available for its implementation. Therefore here in this tutorial, I will show you how to make an Android Bluetooth Low Energy Example, with latest APIs.

Since BLE is still new to Android, some improvements were made in API 21 for the same, where the way to detect low energy Bluetooth devices was changed. This lead to deprecation of some old APIs. Primarily scanning for available Bluetooth LE devices using, mBluetoothAdapter.startLeScan(mLeScanCallback) method is now deprecated. The new API suggests to use startScan method of BluetoothLeScanner class, which can be initialized from the same BluetoothAdapter class. But the problem which many of you must have faced, is these new API methods do not work on old APIs, as they are not backward compatible. Hence here we will make an Android Bluetooth Low Energy example, with backward support till API 18.

Android Bluetooth Low Energy Example

Since BLE was introduced in API 18 and cannot be used on old devices, due to change of Bluetooth specifications. I suggest you to specify the min SDK version to 18 in your app. Next add these permissions and feature tags in the manifest tag of your app manifest:

<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN"/>

<uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

Since I will be printing all the data in logs, there is no need for a layout file, lets have a look at the code for using Bluetooth low energy on Android:

package com.truiton.bleexample;

import android.annotation.TargetApi;
import android.app.Activity;
import android.bluetooth.BluetoothAdapter;
import android.bluetooth.BluetoothDevice;
import android.bluetooth.BluetoothGatt;
import android.bluetooth.BluetoothGattCallback;
import android.bluetooth.BluetoothGattCharacteristic;
import android.bluetooth.BluetoothGattService;
import android.bluetooth.BluetoothManager;
import android.bluetooth.BluetoothProfile;
import android.bluetooth.le.BluetoothLeScanner;
import android.bluetooth.le.ScanCallback;
import android.bluetooth.le.ScanFilter;
import android.bluetooth.le.ScanResult;
import android.bluetooth.le.ScanSettings;
import android.content.Context;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.os.Build;
import android.os.Bundle;
import android.os.Handler;
import android.support.v7.app.ActionBarActivity;
import android.util.Log;
import android.widget.Toast;

import java.util.ArrayList;
import java.util.List;

@TargetApi(21)
public class MainActivity extends ActionBarActivity {
    private BluetoothAdapter mBluetoothAdapter;
    private int REQUEST_ENABLE_BT = 1;
    private Handler mHandler;
    private static final long SCAN_PERIOD = 10000;
    private BluetoothLeScanner mLEScanner;
    private ScanSettings settings;
    private List<ScanFilter> filters;
    private BluetoothGatt mGatt;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        mHandler = new Handler();
        if (!getPackageManager().hasSystemFeature(PackageManager.FEATURE_BLUETOOTH_LE)) {
            Toast.makeText(this, "BLE Not Supported",
                    Toast.LENGTH_SHORT).show();
            finish();
        }
        final BluetoothManager bluetoothManager =
                (BluetoothManager) getSystemService(Context.BLUETOOTH_SERVICE);
        mBluetoothAdapter = bluetoothManager.getAdapter();

    }

    @Override
    protected void onResume() {
        super.onResume();
        if (mBluetoothAdapter == null || !mBluetoothAdapter.isEnabled()) {
            Intent enableBtIntent = new Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE);
            startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT);
        } else {
            if (Build.VERSION.SDK_INT >= 21) {
                mLEScanner = mBluetoothAdapter.getBluetoothLeScanner();
                settings = new ScanSettings.Builder()
                        .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
                        .build();
                filters = new ArrayList<ScanFilter>();
            }
            scanLeDevice(true);
        }
    }

    @Override
    protected void onPause() {
        super.onPause();
        if (mBluetoothAdapter != null && mBluetoothAdapter.isEnabled()) {
            scanLeDevice(false);
        }
    }

    @Override
    protected void onDestroy() {
        if (mGatt == null) {
            return;
        }
        mGatt.close();
        mGatt = null;
        super.onDestroy();
    }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == REQUEST_ENABLE_BT) {
            if (resultCode == Activity.RESULT_CANCELED) {
                //Bluetooth not enabled.
                finish();
                return;
            }
        }
        super.onActivityResult(requestCode, resultCode, data);
    }

    private void scanLeDevice(final boolean enable) {
        if (enable) {
            mHandler.postDelayed(new Runnable() {
                @Override
                public void run() {
                    if (Build.VERSION.SDK_INT < 21) {
                        mBluetoothAdapter.stopLeScan(mLeScanCallback);
                    } else {
                        mLEScanner.stopScan(mScanCallback);

                    }
                }
            }, SCAN_PERIOD);
            if (Build.VERSION.SDK_INT < 21) {
                mBluetoothAdapter.startLeScan(mLeScanCallback);
            } else {
                mLEScanner.startScan(filters, settings, mScanCallback);
            }
        } else {
            if (Build.VERSION.SDK_INT < 21) {
                mBluetoothAdapter.stopLeScan(mLeScanCallback);
            } else {
                mLEScanner.stopScan(mScanCallback);
            }
        }
    }


    private ScanCallback mScanCallback = new ScanCallback() {
        @Override
        public void onScanResult(int callbackType, ScanResult result) {
            Log.i("callbackType", String.valueOf(callbackType));
            Log.i("result", result.toString());
            BluetoothDevice btDevice = result.getDevice();
            connectToDevice(btDevice);
        }

        @Override
        public void onBatchScanResults(List<ScanResult> results) {
            for (ScanResult sr : results) {
                Log.i("ScanResult - Results", sr.toString());
            }
        }

        @Override
        public void onScanFailed(int errorCode) {
            Log.e("Scan Failed", "Error Code: " + errorCode);
        }
    };

    private BluetoothAdapter.LeScanCallback mLeScanCallback =
            new BluetoothAdapter.LeScanCallback() {
                @Override
                public void onLeScan(final BluetoothDevice device, int rssi,
                                     byte[] scanRecord) {
                    runOnUiThread(new Runnable() {
                        @Override
                        public void run() {
                            Log.i("onLeScan", device.toString());
                            connectToDevice(device);
                        }
                    });
                }
            };

    public void connectToDevice(BluetoothDevice device) {
        if (mGatt == null) {
            mGatt = device.connectGatt(this, false, gattCallback);
            scanLeDevice(false);// will stop after first device detection
        }
    }

    private final BluetoothGattCallback gattCallback = new BluetoothGattCallback() {
        @Override
        public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
            Log.i("onConnectionStateChange", "Status: " + status);
            switch (newState) {
                case BluetoothProfile.STATE_CONNECTED:
                    Log.i("gattCallback", "STATE_CONNECTED");
                    gatt.discoverServices();
                    break;
                case BluetoothProfile.STATE_DISCONNECTED:
                    Log.e("gattCallback", "STATE_DISCONNECTED");
                    break;
                default:
                    Log.e("gattCallback", "STATE_OTHER");
            }

        }

        @Override
        public void onServicesDiscovered(BluetoothGatt gatt, int status) {
            List<BluetoothGattService> services = gatt.getServices();
            Log.i("onServicesDiscovered", services.toString());
            gatt.readCharacteristic(services.get(1).getCharacteristics().get
                    (0));
        }

        @Override
        public void onCharacteristicRead(BluetoothGatt gatt,
                                         BluetoothGattCharacteristic
                                                 characteristic, int status) {
            Log.i("onCharacteristicRead", characteristic.toString());
            gatt.disconnect();
        }
    };
}

Bluetooth LE is huge topic, hence the example above only shows how to scan available Bluetooth low energy devices, discover their services and read the basic characteristics of it. The above example shows the best practices to detect a BLE device in an Android app with support up to API 18. To keep it short and simple, instead of writing full code for selecting a Gatt profile/service. I have randomly selected a Generic attribute (Gatt) profile above to print its BluetoothGattCharacteristic object using gatt.readCharacteristic(services.get(1).getCharacteristics().get(0)). To actually read BLE attributes, you may need to write code specifically for your application as there may not be a single way to do it, as there are around 50 Gatt based profile specifications. Hence lets understand each component of Android Bluetooth Low Energy API individually.

Working of Bluetooth LE in Android

As I mentioned BLE has different Gatt profiles, each BLE device has a profile, through which they can act as a server. Like all network devices, Bluetooth LE also works in a client/server manner. Here in the example above, mobile app would act as a client and the BLE device would act as a server.

Scanning Bluetooth Low Energy Devices

In the above example I scanned BLE devices using the highest power consumption mode ScanSettings.SCAN_MODE_LOW_LATENCY. As here my objective was to detect nearby BLE devices immediately. But in total, the new API offers three modes in which nearby BLE devices could be scanned.

• ScanSettings.SCAN_MODE_LOW_POWER – This is the default BLE scan mode, consuming the lowest power, but has a high latency. Good for use when BLE device detection needs to be done in background.
• ScanSettings.SCAN_MODE_BALANCED – This mode scans Bluetooth LE devices in a balanced power consumption mode, with respect to latency.
• ScanSettings.SCAN_MODE_LOW_LATENCY – This mode uses the highest power, when compared to other modes. Also detects the BLE devices fastest, hence should be used when the app is in foreground.

Reading BLE Characteristics in Android

BLE characteristic is the actual data which is served through the BLE device. For example heart rate from a heart rate BLE device is a characteristic. Reading BLE characteristics or getting notified of changed BLE characteristics could be a whole different tutorial. As this could have a huge amount of customizations. Therefore here lets lets discuss the basic part only to get you started.

To read Bluetooth low energy characteristics after scanning, we first need to connect to a BLE device using connectToDevice method as shown above. Then further a connection needs to be established with a Gatt profile using device.connectGatt method, returning connection callbacks to the BluetoothGattCallback class also as shown in the example above. Further when a connection is established we need to discover all the services using gatt.discoverServices() method. This would invoke onServicesDiscovered method, where you can select a service and determine the types of characteristics it has. If the characteristic type is read, then the gatt.readCharacteristic method could be used, which would fire the onCharacteristicRead callback as shown above. But if characteristic type is notify, you may need to set notifications using the setCharacteristicNotification method. More of this could be read from here, as reading Bluetooth Low Energy characteristic notifications is not in our scope. Hope this Android Bluetooth Low Energy example helped you in getting started and scanning your first BLE device. Connect with us on Facebook, Google+ and Twitter for more updates.

Mohit Gupt

Born in New Delhi, India. A software engineer by profession, an android enthusiast and an evangelist. My motive here is to create a group of skilled developers, who can develop something new and good. Reason being programming is my passion, and also it feels good to make a device do something you want. In a very short span of time professionally I have worked with many tech firms. As of now too, I am employed as a senior engineer in a leading tech company. In total I may have worked on more than 20 projects professionally, and whenever I get spare time I share my thoughts here at Truiton.