Background scanning and comm

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.

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.

The first order of business for background BLE comm is to enable it in your app's Capabilities. This will allow your app to remain open for a small period of time after it goes to background to perform its BLE tasks.

• Go to Signing and Capabilities → Check Uses Bluetooth LE accessories.

Then, inform your AbleManager that you plan on supporting background mode, before running initialize:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AbleManager.shared.supportsBackground = true
    AbleManager.shared.initialize()
 }

After this, you don't have to worry about anything. AbleManager will track your app's state and allow or disallow certain operations, based on if they're available or not. You'll get appropriate error callbacks and logs to indicate if something isn't available.

AbleManager also automatically handles state restoration, if you provide it with launch options in initialize:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AbleManager.shared.supportsBackground = true
    AbleManager.shared.initialize(launchOptions: launchOptions)
 }

This will automatically restore AbleDevices to storage and re-set the quality of service. You can receive the restoration data in the onRestore callback:

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    AbleManager.shared.supportsBackground = true
    AbleManager.shared.initialize(launchOptions: launchOptions, onRestore: { data in
        // handle your custom restoration        
    })
 }