Android - pairing and bonding

This guide is for Android only. iOS does not require you to pair and bond with a peripheral before using it - you just connect at the start of communication.

Before you start, follow the introductory steps in this guide to make sure AbleLib is set up properly, and that your phone has all the necessary components and permissions.

Pairing with a peripheral is as simple as scanning was - use AbleManager's pair method, and you'll get back the paired AbleDevice. The library will take care of showing the pairing dialog for PIN input, if it is mandated by the peripheral.

Pairing is an async operation and there are three ways of going about it - coroutines, callback or the listener. Let's start with the callback approach - it attempts to pair with the given AbleDevice, and returns a Result<AbleDevice>. The returned AbleDevice may or may not be the same one that you provided, based on the operations performed on it by the OS.

myAbleDevice.pair { result ->
        result.onSuccess { 
            // handle the paired device
        }.onFailure {
            // an exception has occurred
        }
}

// OR

AbleManager.shared.pair(myAbleDevice) { result ->
        // same as the above
}

The coroutines approach is cleaner and avoids callback hell:

suspend fun pairWithDevice() {
    val myDevice = AbleDeviceStorage.default.findByName("my awesome device")
    try {
        val pairedDevice = myDevice.pair()
    } catch (e: Exception) {
        // handle the exception
    }
}

The listener is, for the most part, a more simply laid out version of the Result<AbleDevice>

AbleManager.shared.pair(myAbleDevice, object : AblePairingScanListener {
    override fun onPaired(device: AbleDevice) {
        // pairing done successfully
    }

    override fun onError(e: Exception) {
        // an error has occurred
    }
})

If you need to cancel an ongoing pairing, use cancelPairing:

AbleManager.shared.cancelPairing()
Importing bonded devices and automatic unbonding

Android allows you to access devices that your phone previously bonded with. AbleLib takes advantage of this to allow you to trivially add all phone-level bonded devices to your AbleDeviceStorage:

AbleManager.shared.importBondedDevices()

Android also allows us to programatically unpair bonded devices and remove them from your AbleDeviceStorage. You can do this per device or for all devices at once:

AbleManager.shared.removeDeviceAndUnpair("address")
// or
AbleManager.shared.removeAllDevicesAndUnpair()