kmp-ble
0.9.0indexedScan, connect, read/write and observe GATT; advertise and host GATT servers; perform Nordic Secure DFU; type-safe profile parsing, composable codecs, reconnection and bonding support.
1
Stars
—
Used by
dependents
74
Health
/ 100
kmp-ble
Kotlin Multiplatform BLE library for Android and iOS.
Modules
Setup
Android / KMP (Gradle)
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.atruedev:kmp-ble:0.9.0")
// Optional modules
implementation("com.atruedev:kmp-ble-profiles:0.9.0")
implementation("com.atruedev:kmp-ble-dfu:0.9.0")
implementation("com.atruedev:kmp-ble-codec:0.9.0")
implementation("com.atruedev:kmp-ble-codec-serialization:0.9.0")
}
}
}
Initialize in your Application.onCreate() (Android only):
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
KmpBle.init(this)
}
}
iOS (Swift Package Manager)
In Xcode: File > Add Package Dependencies and enter:
https://github.com/gary-quinn/kmp-ble
Select the version and add KmpBle to your target.
import KmpBle
Usage
Scan for devices
Standard service UUIDs are provided as constants in ServiceUuid. For custom/proprietary
services, use the UUID from your device's documentation or GATT profile.
See: Bluetooth SIG Service UUIDs
// Common code - works on both Android and iOS
val scanner = Scanner {
timeout = 30.seconds
emission = EmissionPolicy.FirstThenChanges(rssiThreshold = 10)
filters {
match { serviceUuid(ServiceUuid.HEART_RATE) }
}
}
scanner.scanEvents.collect { event ->
when (event) {
is ScanEvent.Found -> {
val ad = event.advertisement
println("Found: ${ad.name} (${ad.identifier}) rssi=${ad.rssi}")
}
ScanEvent.Failed -> println()
}
}
scanner.close()
Monitor adapter state
val adapter = BluetoothAdapter()
adapter.state.collect { state ->
when (state) {
BluetoothAdapterState.On -> println("Bluetooth ready")
BluetoothAdapterState.Off -> println("Bluetooth off")
BluetoothAdapterState.Unauthorized -> println("Permission denied")
else -> {}
}
}
Connect and read/write
val peripheral = advertisement.toPeripheral()
peripheral.connect()
val hrChar = peripheral.findCharacteristic(
serviceUuid = uuidFrom("180d"),
characteristicUuid = uuidFrom("2a37"),
)!!
// Read
val value = peripheral.read(hrChar)
// Write (explicit WriteType required)
peripheral.write(hrChar, byteArrayOf(0x01), WriteType.WithResponse)
// Observe notifications
peripheral.observeValues(hrChar).collect { data ->
println("Heart rate: ${data[]}")
}
peripheral.disconnect()
peripheral.close()
Profiles (kmp-ble-profiles)
Type-safe GATT profile parsing via Peripheral extension functions:
// Heart Rate
peripheral.heartRateMeasurements().collect { measurement ->
println("BPM: ${measurement.heartRate}")
println("RR intervals: ${measurement.rrIntervals}")
println()
}
location = peripheral.readBodySensorLocation()
level = peripheral.readBatteryLevel()
peripheral.batteryLevelNotifications().collect { println() }
info = peripheral.readDeviceInformation()
println()
Supported profiles: Heart Rate, Battery, Device Information, Blood Pressure, Glucose, Cycling Speed and Cadence.
Codec (kmp-ble-codec)
Typed read/write with composable decoders:
Serialization codec (kmp-ble-codec-serialization)
CBOR adapters via kotlinx-serialization. Bridge @Serializable types to the
BleCodec surface so they slot into framed L2CAP streams or characteristic
read/write paths without writing a hand-rolled decoder:
@Serializable
data class Reading(val timestampMs: Long, val celsius: Double)
val codec = cborCodec<Reading>()
// Framed L2CAP stream of typed values
l2cap.writeFramed(Reading(1_700_000_000_000, 21.5), codec)
l2cap.framedIncoming(codec).collect { reading -> render(reading) }
DFU (kmp-ble-dfu)
Firmware updates supporting Nordic Secure DFU, MCUboot SMP (Zephyr/Mynewt), and Espressif ESP OTA:
// Auto-detect protocol from peripheral's GATT services
val controller = DfuController.create(peripheral)
// Or specify explicitly
val controller = DfuController(peripheral, McuBootDfuProtocol())
controller.performDfu(firmware).collect { progress ->
when (progress) {
is DfuProgress.Transferring -> println("${(progress.fraction * 100).toInt()}%")
DfuProgress.Completed -> println()
DfuProgress.Failed -> println()
-> {}
}
}
controller.abort()
Each protocol has its own firmware parser:
// Nordic Secure DFU (.zip)
val nordic = FirmwarePackage.Nordic.fromZipBytes(zipData)
// MCUboot SMP (.bin)
val mcuboot = FirmwarePackage.McuBoot.fromBinBytes(binData)
// Espressif ESP OTA (.bin)
val esp = FirmwarePackage.EspOta.fromBinBytes(binData)
ESP OTA supports custom service UUIDs for vendor flexibility:
val controller = DfuController(peripheral, EspOtaDfuProtocol())
controller.performDfu(firmware, DfuOptions(
transport = DfuTransportConfig.EspOta(
serviceUuid = uuidFrom("your-custom-service-uuid"),
)
))
GATT Server and Advertising
val server = GattServer {
service(uuidFrom()) {
characteristic(uuidFrom()) {
properties { read = ; notify = }
permissions { read = }
onRead { device -> BleData(byteArrayOf(, )) }
}
}
}
server.()
advertiser = Advertiser()
advertiser.startAdvertising(AdvertiseConfig(
serviceUuids = listOf(uuidFrom()),
connectable = ,
))
server.notify(uuidFrom(), device = , BleData(byteArrayOf(, )))
extAdvertiser = ExtendedAdvertiser()
extAdvertiser.startAdvertisingSet(ExtendedAdvertiseConfig(
serviceUuids = listOf(uuidFrom()),
primaryPhy = Phy.Le1M,
secondaryPhy = Phy.Le2M,
))
Bonding
// Proactive bonding
peripheral.connect(ConnectionOptions(bondingPreference = BondingPreference.Required))
// Observe bond state
peripheral.bondState.collect { state ->
println("Bond: $state") // NotBonded, Bonding, Bonded, Unknown
}
// Remove bond (Android only)
@OptIn(ExperimentalBleApi::class)
val result = peripheral.removeBond()
Reconnection
peripheral.connect(ConnectionOptions(
reconnectionStrategy = ReconnectionStrategy.ExponentialBackoff(
initialDelay = 1.seconds,
maxDelay = 30.seconds,
maxAttempts = 10,
)
))
Connection Recipes
// Pre-configured connection options for common use cases
peripheral.connect(ConnectionRecipe.MEDICAL) // strict bonding, no auto-connect
peripheral.connect(ConnectionRecipe.FITNESS) // reconnection, if-required bonding
peripheral.connect(ConnectionRecipe.IOT) // auto-connect, no bonding
peripheral.connect(ConnectionRecipe.CONSUMER) // balanced defaults
Permissions
when (val result = checkBlePermissions()) {
is PermissionResult.Granted -> { /* ready to scan */ }
is PermissionResult.Denied -> { /* request permissions */ }
is PermissionResult.PermanentlyDenied -> { /* open settings */ }
}
Logging
BleLogConfig.logger = PrintBleLogger() // stdout/logcat
// or
BleLogConfig.logger = BleLogger { event -> Timber.d("BLE: $event") }
Test without hardware
Sample Apps
BLE Toolkit (sample/)
Production-grade BLE utility app (Android + iOS) with tab-based navigation, composed operation classes, and polished UX:
- Scanner with RSSI/name filtering, sorting, device categorization, manufacturer name resolution
- Device Detail with GATT service browser, value display in HEX/UTF-8/Decimal/Binary, connection recipes, bonding
Quickstart (sample-quickstart/)
Minimal ~150-line single-screen app: scan, tap, connect, read first characteristic, display value. No ViewModel, no navigation - the "Getting Started in 5 Minutes" reference.
Architecture
See ARCHITECTURE.md for design details and STREAMS.md for an end-to-end recipe on typed L2CAP streams (codec + framing + accept loop).
Requirements
- Kotlin 2.3.0+
- Android minSdk 33
- iOS 15+
- kotlinx-coroutines 1.10+
Documentation
Contributing
After cloning, enable the repo's pre-commit hooks once:
git config core.hooksPath .githooks
The hook blocks Unicode typography characters (em/en-dash, smart quotes,
ellipsis, NBSP) in staged content. See AGENTS.md for the full list
and the typo-ok bypass.
License
Apache 2.0 - Copyright (C) 2026 Gary Quinn