Background scanning and comm

This guide presents options for scanning and communicating with BLE devices while your app is in the background. Android and iOS have profoundly different methods of managing background state, but AbleLib allows you to make easy use of, while also taking care of all the potential issues.

Android allows us to scan for and communicate with BLE peripherals while our app is in the background. There are two ways of going about it, mostly dictated by Android background limitations first introduced in Android O.

  1. A background service that runs in the background while your app is running, and for a very short while after it goes to background, or
  2. A foreground service that runs even if your app is backgrounded, but must post a notification to tell the user that your app is in fact doing some work in the background.

AbleLib takes care of all of that, and allows you to readily deploy background BLE processes with minimal effort.

You can only run a single BLE service at the time, as multiple instances would try to use the same resources, resulting in a lock.

Start off by calling AbleManager#setUpService to set all relevant parameters:

AbleManager.shared.setUpService(
    serviceClass = AbleTask::class.java,
    notification = AbleTask.defaultNotification(context, "My App", "Hey, running!", R.drawable.icon, MyMainActivity::class.java),
    backgroundScanOutsideApp = true,
    backgroundScanInApp = true
)                     

The parameters are as follows:

  1. serviceClass - the Service class that contains your scanning logic. It must be AbleTask or its subclass. Check out this section for more info.
  2. notification - the Notification that'll be shown to the user when the service is ran in the foreground. You can provide a notification of your own, or make use of AbleService#defaultNotification, which will construct a notification with the provided title, message and icon, and will open the provided Activity when tapped.
  3. backgroundScanOutsideApp - if the service should scan when the app is backgrounded.
  4. backgroundScanInApp - if the service should scan when the app is foregrounded.

After your service is set up, you can start it with AbleManager.refreshBackgroundServiceState, which will be your go-to point for whenever you make changes with setUpService. AbleManager will automatically detect your app state and start/stop the service in the appropriate mode, foreground or background, depending on backgroundScanOutsideApp and backgroundScanInApp.

AbleManager.shared.refreshBackgroundServiceState() // call this whenever you need to (re)start/stop your service

You can manually stop and remove the service with AbleManager.removeService:

AbleManager.shared.removeService()
AbleTask info

In its default implementation, AbleTask lives in the background and scans for nearby paired peripherals. Once it finds any, it sends a broadcast with action = AbleTask.ACTION_DEVICE_FOUND, and the found AbleDevice packed as a Parcelable extra with key AbleService.DEVICE.

The AbleTask class is open and can be subclassed in order to implement any behaviour that you'd like. The best way of going about it is just to override open methods onStart and onStop, which, in the default version, contain the logic for starting and stopping the scanning process. Then, make sure to pass your subclass's class in setUpService.