The BleSetupHelper class is a convenience class to effortlessly handle getting the necessary permissions for BLE scans to work on Android 6 and up. This can be quite an annoying experience, and we've chewed this piece of annoyance up for you. Of course, you can always ignore it, and roll your own implementation.

The helper will show dialogs to your user explaining what's needed and being requested. There's even pre formatted text for each dialog, which has multiple languages available.

How many languages does the helper come with?

18. English is the default, which is hardcoded (if you use the jar, this is all you will get without implementing your own), and 17 additional language codes.

The language codes are:

  1. English (en) [default]
  2. Czech (cs)
  3. Danish (da)
  4. German (de)
  5. Spanish (es)
  6. French (fr)
  7. French - Canada (fr-rCA)
  8. Italian (it)
  9. Japanese (ja)
  10. Korean (ko)
  11. Dutch (nl)
  12. Norwegian nn
  13. Polish (pl)
  14. Portuguese - Brazil (pt-rBR)
  15. Russian (ru)
  16. Swedish (sv)
  17. Chinese (China) zh-rCN
  18. Chinese (Taiwan) zh-rTW

What exactly is needed to successfully run a BLE scan on Android Marshmallow (6.0) and higher?

  1. Bluetooth must be on
  2. Location services permission a. You must declare android.permission.ACCESS_COARSE_LOCATION in your manifest file (for Android Q and beyond, you will have to use android.permission.ACCESS_FINE_LOCATION) b. You must request user permission at runtime
  3. Location services must be on

The helper will turn the bluetooth radio on, if it is not already. Next, it will request location permission, if they have not been granted. Then it will turn on location services, if they are not on. Finally, any custom permissions are handled.

Simple Example Usage

BleManagerConfig config = new BleManagerConfig();
BleManager manager = BleManager.get(this, config);
BleSetupHelper.runEnabler(manager, this, result ->
    if (result.getSuccessful())
        // Do whatever you want to do with Bluetooth now.
        // You may want to show something to the user here to explain
        // that bluetooth scanning will not work without all the requested
        // permissions and services are turned on

Can I use the helper class to handle my own custom permissions?

Yes! The helper was built with the idea that if you wanted to roll extra permissions into the flow, it would be easy to do.

Custom permission example

protected void onCreate(Bundle savedInstanceState)
   BleManagerConfig config = new BleManagerConfig();
   BleManager mgr = BleManager.get(this, config);
   BleSetupHelper helper = new BleSetupHelper(mgr, this, result ->
      if (result.getSuccessful())
         // TODO BLE is fully enabled, and all permissions including custom are granted
   helper.addCustomPermission("My custom permission");
   helper.setImpl(new MyPermissionHelper());

private static class MyPermissionHelper extends BleSetupHelper.BluetoothEnablerImpl
  boolean m_permissionGranted = false;

  public void requestCustomPermission(Object metadata)
  {   // TODO - Implement code to actually request the permission
  m_permissionGranted = true;

  public boolean checkIsCustomPermissionEnabled(Object metadata)
  {   // TODO - Actually check if the permission has been granted
 return m_permissionGranted;

  public boolean checkIsCustomPermissionRequired(Object metadata)
  {   // We're just going to say that this permission is always required
     return true;

What about background scanning on Android 10+?

Android 10 brought about more permission changes, in that if you would like your app to actually get any results from a BLE scan while in the background, you have to request background location. This requires adding this to your app's AndroidManifest.xml file:

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

You should also set the option requestBackgroundOperation to true before running the BleSetupHelper:

BleManagerConfig config = new BleManagerConfig();
config.requestBackgroundOperation = true;
BleManager mgr = BleManager.get(this, config);
BleSetupHelper.runEnabler(mgr, this, result ->
    if  (result.getSuccessful())
        // Permissions have all been granted.