11012599
11012599


An easy-to-use, kotlin-friendly BLE library for Android.

To install

  • Step 1. Add the JitPack repository to yours Project gradle file
allprojects { repositories { ... maven { url 'https://jitpack.io' } }
}
  • Step 2. Add the implementation dependency to yours App gradle file
dependencies { ... implementation 'com.github.LeandroSQ:android-ble-made-easy:1.3.0' ...
}
  • Step 3. Gradle Sync and you’re ready to go!

Core functions

Life cycle

The library accepts use in both an activity and a fragment!

val ble = BLE(activity = this)// orval ble = BLE(fragment = this)

Automatic handle authorizations

The library will request the permissions for you.

Asynchronous:

ble.verifyPermissionsAsync( rationaleRequestCallback = { next -> // Include your code to show an Alert or UI explaining why the permissions are required // Calling the function bellow if the user agrees to give the permissions next() }, callback = { granted -> if (granted) { // Continue your code.... } else { // Include your code to show an Alert or UI indicating that the permissions are required } }
)

Coroutines:

GlobalScope.launch { val granted = ble.verifyPermissions( rationaleRequestCallback = { next -> // Include your code to show an Alert or UI explaining why the permissions are required // Calling the function bellow if the user agrees to give the permissions next() } ) if (granted) { // Continue your code.... } else { // Include your code to show an Alert or UI indicating that the permissions are required }
}

Automatic switch on of the bluetooth adapter

The library requests to enable the bluetooth hardware when it is powered off.

Asynchronous:

ble.verifyBluetoothAdapterStateAsync { active -> if (active) { // Continue your code... } else { // Include your code to show an Alert or UI indicating that the Bluetooth adapter is required to be on in order to your project work }
}

Coroutines:

GlobalScope.launch { if (ble.verifyBluetoothAdapterState()) { // Continue your code... } else { // Include your code to show an Alert or UI indicating that the Bluetooth adapter is required to be on in order to your project work }
}

Automatic activation of location services

The library requests that location services be enabled whenever they are turned off.

Asynchronous:

ble.verifyLocationStateAsync{ active -> if (active) { // Continue your code... } else { // Include your code to show an Alert or UI indicating that Location is required to be on in order to your project work }
}

Coroutines:

GlobalScope.launch { if (ble.verifyLocationState()) { // Continue your code... } else { // Include your code to show an Alert or UI indicating that Location is required to be on in order to your project work }
}

Asynchronous and coroutines

You can use the library with both callbacks and coroutine functions stopped. The callback functions have the suffix ‘async’. And requires a HOF callback as a parameter.

In other words, the handling of Bluetooth connections with graceful connection shutdown waits until the current operations (reading and writing) are completed before closing the connection

JetPack contracts ready!

The library uses the new JetPack Contract API to automatically manage entitlements and adapter activation for you.

Compatible with older API levels

Theoretically compatible down to API 18, but targeting API 21+.

Well documented!

All of the functions and variables that you will be using are very well documented with KotlinDOC. Here’s how you can get auto-complete information in Android Studio. But if you want to take a look at it without installing it … you can take a look at the documentation generated by dokka

Both low-level bytes and string conversion

The library gives you the ability to receive and send raw bytes if you want. Or you can choose to have your strings encoded and decoded automatically.

Automatically treats the pain of known problems

For example, take output 183108 where lollipop devices will not work properly without a workaround to connect them.

Or the well-known BLE 133 bug! This library is the nightmare of anyone who has worked with BLE on Android. It contains a set of techniques that can be used to circumvent it

use

After instantiating the BLE Class…

Fast scan for a specific device

If you already know the device you want to connect to, here’s what you can do with it:

Asynchronous:

ble.scanForAsync( // You only need to supply one of these, no need for all of them! macAddress = "00:00:00:00", name = "ESP32", service = "00000000-0000-0000-0000-000000000000", onFinish = { connection -> if (connection != null) { // And you can continue with your code it.write("00000000-0000-0000-0000-000000000000", "Testing") } else { // Show an Alert or UI with your preferred error message about the device not being available } }, onError = { errorCode -> // Show an Alert or UI with your preferred error message about the error }
)// It is important to keep in mind that every single one of the provided arguments of the function shown above, are optionals! Therefore, you can skip the ones that you don't need.

Coroutines:

GlobalScope.launch { // You can specify filters for your device, being them 'macAddress', 'service' and 'name' val connection = ble.scanFor( // You only need to supply one of these, no need for all of them! macAddress = "00:00:00:00", name = "ESP32", service = "00000000-0000-0000-0000-000000000000" ) // And it will automatically connect to your device, no need to boilerplate if (connection != null) { // And you can continue with your code it.write("00000000-0000-0000-0000-000000000000", "Testing") } else { // Show an Alert or UI with your preferred error message about the device not being available }
}

Scanning from BLE devices

Asynchronous:

ble.scanAsync( duration = 10000, onDiscover = { device -> // Update your UI with the newest found device, in real time }, onFinish = { devices -> // Continue with your code handling all the devices found }, onError = { errorCode -> // Show an Alert or UI with your preferred error message }
)

Coroutines:

GlobalScope.launch { try { // Continue with your code handling all the devices found val devices = ble.scan(duration = 10000) } catch (e: Exception) { // Show an Alert or UI with your preferred error message } catch (e: ScanFailureException) { // Show an Alert or UI with your preferred error message }
}

Or you can use the scanning method without timeout and just stop manually

ble.scanAsync( duration = 0, // Disables the timeout onDiscover = { device -> // Update your UI with the newest found device, in real time }, onFinish = { devices -> // Continue with your code handling all the devices found }, onError = { errorCode -> // Show an Alert or UI with your preferred error message }
)// Stops your scan manually
ble.stopScan()

Manually connect to a discovered device

After a successful scan, you have your bluetooth device, now it’s time to connect to it!

ble.connect(device)?.let { connection -> // Continue with your code val value = connection.read("00000000-0000-0000-0000-000000000000") connection.write("00000000-0000-0000-0000-000000000000", "0") connection.close()
}

Made with <3 by Leandro Quevedo

LEAVE A REPLY

Please enter your comment!
Please enter your name here