README suggestion

[mobilekosmos]

For a quick start something like this would be beneficial, I needed to use AI to check how to use the lib:

Android Quick start:
Add the library to your toml file:

[versions]
nordic-ble = "2.0.0-alpha08" # check latest: https://github.com/NordicSemiconductor/Kotlin-BLE-Library/releases

[libraries]
nordic-ble-client-android = { module = "no.nordicsemi.kotlin.ble:client-android", version.ref = "nordic-ble" }

Reference it in your module:

implementation(libs.nordic.ble.client.android)

In your ViewModel:

    private val central: CentralManager by lazy {
        CentralManager.Factory.native(applicationContext, viewModelScope)
    }

    data class UiDevice(
        val id: String,           // PeripheralId (string)
        val name: String?,        // Advertised name (may be null)
        val rssi: Int?,           // Last known RSSI if provided by scan result
    )

    private val _devices = MutableStateFlow<List<UiDevice>>(emptyList())
    val devices: StateFlow<List<UiDevice>> = _devices.asStateFlow()

    private val seenIds = linkedSetOf<String>() // preserves discovery order
    private var scanJob: Job? = null

    fun startScan(duration: Duration = 5.seconds) {
        stopNordicBleScan()
        Timber.d("BLE: starting scan for ${duration.inWholeMilliseconds} ms")

        scanJob = central
            .scan(duration) {
                // Add filters if needed, e.g.:
                // ServiceUUID(UUID.fromString("0000180F-0000-1000-8000-00805F9B34FB"))
                // Name("MyDevice")
                ManufacturerData(BleRepo.HAGLEITNER_MANUFACTURER_ID)
            }
            .onEach { scanResult ->
                val p = scanResult.peripheral
                val id = p.identifier
                if (seenIds.add(id)) {
                    Timber.i("BLE NEW: name='${p.name ?: "<unknown>"}' id='$id' rssi=${scanResult.rssi}")
                    _devices.value = _devices.value + UiDevice(id, p.name, scanResult.rssi)
                } else {
                    _devices.value = _devices.value.map {
                        if (it.id == id) it.copy(name = p.name ?: it.name, rssi = scanResult.rssi) else it
                    }
                }
            }
            .launchIn(viewModelScope)
    }

    fun stopNordicBleScan() {
        scanJob?.cancel()
        scanJob = null
        Timber.i("BLE: scan cancelled")
    }

    override fun onCleared() {
        super.onCleared()
        stopNordicBleScan()
    }

Just a quick example, not the best, but working one.

Btw., how do I set the scan priority SCAN_MODE_LOW_LATENCY?

[philips77]

In the current version this is the only mode that the library is using:

Kotlin-BLE-Library/client-android/src/main/java/no/nordicsemi/kotlin/ble/client/android/internal/NativeCentralManagerImpl.kt

Lines 234 to 244 in a19159e

	// Use the most optimal scan mode for low latency immediate scanning.
	val settings = NativeScanSettings.Builder()
	.apply {
	// TODO Scan settings could be configurable.
	setScanMode(NativeScanSettings.SCAN_MODE_LOW_LATENCY)
	if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
	setLegacy(false)
	setPhy(NativeScanSettings.PHY_LE_ALL_SUPPORTED)
	}
	}
	.build()

This is the most commonly used mode for in-app scanning.

As we want the source code to be easy to read and verbose, we would rather create a new API for "background" scanning, rather than allowing setting the mode. In Android API there's scan mode, callback type, match mode, num of matches, scan type and no one knows what they mean. Even the documentation doesn't say much. The intention is for us to test it, understand, and make readable API and documentation. Easy to use.

[philips77]

Also, the library is designed in a way, that you should be able to import

implementation(libs.nordic.ble.client.core.android)

and use the core Android library in the app, and only use the "native" manager from no.nordicsemi.kotlin.ble:client-android:

CentralManager.Factory.native(applicationContext, viewModelScope)

in the :app module using dependency injection.

Whem I'm done with the mock implementation you should be able to switch to:

CentralManager.Factory.mock(environment, viewModelScope)

with

implementation(libs.nordic.ble.client.android.mock)

Have a look at the sample:
https://github.com/NordicSemiconductor/Kotlin-BLE-Library/tree/version/2.0/sample/src