Usage

SimpleDroidBLE is an Android-specific package that provides an API similar to SimpleBLE, using modern Kotlin idiomatic code.

This code is currently under active development and some features are not yet implemented or their API might change. It is useful for Android-first experiments and applications that want a Kotlin API directly on top of the SimpleBLE Android backend.

Requirements

Android API 31 or newer.
Android Studio.
Android NDK. The repository currently builds with NDK r29.
Bluetooth permissions declared in AndroidManifest.xml and requested at runtime.

Consuming Locally

If you want to use SimpleDroidBLE as part of your project from a local copy, you can do so by adding the following to your settings.gradle or settings.gradle.kts file. Make sure this include is before your include(":app") statement.

Groovy:

includeBuild("path/to/simpledroidble") {
    dependencySubstitution {
        substitute module("org.simpleble.android:simpledroidble") with project(":simpledroidble")
    }
}

Kotlin:

includeBuild("path/to/simpledroidble") {
    dependencySubstitution {
        substitute(module("org.simpleble.android:simpledroidble")).using(project(":simpledroidble"))
    }
}

Then, inside your build.gradle or build.gradle.kts file, you can add the following dependency:

Groovy:

dependencies {
    implementation "org.simpleble.android:simpledroidble"
}

Kotlin:

dependencies {
    implementation("org.simpleble.android:simpledroidble")
}

Android Permissions

Declare the Bluetooth permissions your app needs:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

Then set the activity context and request permissions before using the adapter APIs:

import org.simpleble.android.SimpleDroidBle
import java.lang.ref.WeakReference

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        SimpleDroidBle.contextReference = WeakReference(this)

        if (!SimpleDroidBle.hasPermissions) {
            SimpleDroidBle.requestPermissions()
            return
        }

        // Safe to create adapters after permissions are available.
    }

    override fun onRequestPermissionsResult(
        requestCode: Int,
        permissions: Array<out String>,
        grantResults: IntArray
    ) {
        super.onRequestPermissionsResult(requestCode, permissions, grantResults)
        SimpleDroidBle.handleOnRequestPermissionsResult(requestCode, permissions, grantResults)
    }
}

First scan

The Android API uses coroutines and flows for operations and events:

val adapter = Adapter.getAdapters().first()

CoroutineScope(Dispatchers.Main).launch {
    adapter.onScanFound.collect { peripheral ->
        Log.d("SimpleBLE", "Found ${peripheral.identifier} [${peripheral.address}]")
    }
}

CoroutineScope(Dispatchers.Main).launch {
    adapter.scanFor(5000)
}

Feature status

Adapter discovery, scanning, connecting, service discovery, characteristic reads, notifications, and indications are available.
writeRequest and writeCommand are currently placeholders in the alpha SimpleDroidBLE API.
For a fuller app structure, including permission flow and Compose screens, see Examples.