Nordic Android-BLE-Library: A BleManager for GATT Work on Android

What Android-BLE-Library fixes about Android's BluetoothGatt

Android's own Bluetooth LE stack gives you a GATT client callback and leaves the rest to you. Serialising operations so two requests never overlap, retrying a dropped connection, splitting a payload longer than the negotiated MTU, and cleaning up a stale GATT cache are all things every BLE app ends up writing. Nordic Semiconductor's Android-BLE-Library packages those into a single BleManager class. The README lists the scope plainly: connection with automatic retries, service discovery, bonding and bond removal, automatic handling of Service Changed indications, device initialization, asynchronous and synchronous operations through a queue, splitting and merging long packets, MTU and connection priority requests, PHY preferences, RSSI reads, cache refresh, Reliable Write, operation timeouts, error handling and logging.

The audience is narrow but real. This is for Android developers integrating a specific peripheral: a wearable, a sensor, a medical device, a piece of industrial hardware. It is not a general Bluetooth toolkit. The README is explicit that the library does not provide support for scanning and recommends the separate Android Scanner Compat Library instead. If your product's core loop is discovering nearby devices, this library is not the piece you need first.

There is also a successor in progress. The README carries a note that Nordic is working on a Kotlin BLE Library, version 2.0, which will eventually replace this one, and that version 2 is not backward compatible with this library. At the time of the note, that version is described as being in an early development stage and not recommended for production. So the library you would adopt today is the one being replaced later, and the replacement is not ready.

How BleManager drives the GATT queue

The central object is BleManager. You subclass it, and each subclass represents one peripheral type. The README describes the operational model as a queue: BLE operations are executed asynchronously or synchronously through it, so requests do not collide the way raw BluetoothGatt calls can when a caller fires a read while a write is still in flight. Around that queue sit the features that make the abstraction worth having: automatic retries on connection, service discovery after connect, optional bonding, automatic handling of Service Changed indications so a peripheral that reconfigures its attribute table does not leave your app holding stale handles, and timeouts on connect, disconnect and wait-for-notification requests.

Two mechanisms deserve a closer look because they carry trade-offs. Long-packet handling splits outgoing writes and merges incoming reads across the MTU, with progress observable through splitWithProgressFlow and mergeWithProgressFlow according to the version 2.4 release notes. That is the difference between a payload larger than 20 bytes working and silently truncating. Separately, cache refresh and bond removal are documented as using reflections. Reflection against non-public Android internals is a known source of breakage across OS versions, and the README presents it as a feature rather than flagging the risk. Treat those two as the parts most likely to need attention on a new Android release.

On the Kotlin side, the ble-ktx module layers coroutines and Flow over the same manager: suspend variants of requests, asFlow on value-changed callbacks, connection and bonding state as Flow, and a JsonMerger class for devices that send a JSON document across several packets. The ble-livedata module instead exposes ObservableBleManager with state and bondingState as LiveData for projects still on that pattern. A GATT server implementation has been available since version 2.2, and version 2.6 added a server-only mode via attachClientConnection(BluetoothDevice) as an alternative to connect(BluetoothDevice).

Adding the dependency and running a first connection

The library is published on Maven Central, so the install is a single Gradle dependency line. The README gives the coordinates for version 2.11.0. The base artifact is no.nordicsemi.android:ble. If you want the Kotlin extensions, add ble-ktx instead or alongside it; for parsers of common Bluetooth SIG characteristics, add ble-common. The README notes that the last version not migrated to AndroidX is 2.0.5, which matters if you are on an older support-library codebase.

implementation 'no.nordicsemi.android:ble:2.11.0'

For a Kotlin project that wants coroutines and Flow on top of the same manager, the README lists a separate artifact. Adding it pulls in the suspend and Flow helpers described in the version 2.3 and 2.4 notes.

implementation 'no.nordicsemi.android:ble-ktx:2.11.0'

If you prefer to build the library from source rather than consume the artifact, the README documents importing it as a module. You clone the repository next to your project and add an includeBuild line to settings.gradle. The README also states the library uses Java 17 features and that projects on older Android Studio versions need compile options set accordingly.

if (file('../Android-BLE-Library').exists()) {
    includeBuild('../Android-BLE-Library')
}

After adding the dependency, the practical first use is to subclass BleManager for your peripheral and connect to a BluetoothDevice. The repository ships three example projects under examples/: ble-gatt-client, ble-gatt-server and trivia. The README does not walk through a connect call inline, so the example projects are the reference to read for the exact subclassing and callback wiring. Expect to implement service discovery handling and your own characteristic callbacks on top of the manager; the library removes the queueing and retry work, not the protocol work.

Where the library stops: scanning, reflection and the Kotlin successor

The first limitation is stated by the project itself. There is no scanning support. The README recommends the Android Scanner Compat Library for that, which brings newer scanning features to older platforms. If you adopt Android-BLE-Library expecting a complete Bluetooth LE stack, you will end up with two dependencies and two mental models. That is a deliberate split, not an oversight, but it changes your dependency graph.

The second is the reflection use. Cache refresh and bond removal are implemented with reflections, per the feature list. Reflection into Android internals is fragile by nature: it depends on fields and methods that are not part of the public SDK and can change or be restricted. The library treats this as an accepted cost, and the feature list presents both without a caveat. If your app ships to a wide device fleet across many OS versions, that is the code path to watch when a new Android version lands.

The third is lifecycle. The README's own note says a new Kotlin BLE Library, version 2.0, will eventually replace this one and is not backward compatible with it. At the time of that note, version 2 is described as early development and not recommended for production. So you are adopting a library with a known end state that is not yet reachable. That is a normal situation for a vendor-maintained SDK, but it should be part of the decision, not discovered later. The repository does include a MIGRATION.md file, which suggests migration guidance exists for users moving between versions.

Finally, the minimum toolchain. Version 2.7 migrated the library to Java 17 because of the minimum supported version in Android Studio Giraffe. If your build is pinned to an older toolchain, the module-import path in the README requires you to set sourceCompatibility and targetCompatibility to VERSION_1_17, and Kotlin projects to set jvmTarget to 1.17.

Android-BLE-Library compared with the Kotlin BLE Library

The most relevant alternative is not a third-party project but Nordic's own successor. The README lists the differences directly. Kotlin BLE Library version 2.0 is 100% Kotlin code, supports scanning with scan results as Flow, supports Bluetooth LE advertising, supports mocking BLE devices for testing, and expresses all BLE operations with suspend functions or Flows. Android-BLE-Library is Java-based, offers Kotlin extensions through a separate ble-ktx module, does not scan, and exposes its API through a queue of requests with callback and suspend variants.

The practical difference is where the concurrency model lives. In Android-BLE-Library you subclass BleManager and the library queues requests for you; in the Kotlin library the operations themselves are suspend functions and Flows, so coroutine structure is the primary way you sequence work. The Kotlin library also covers advertising and device mocking, neither of which appears in this library's feature list. Mocking matters if you want BLE flows in automated tests without hardware.

The catch is readiness. The README states the Kotlin library is in an early development stage and not recommended for production use, while Android-BLE-Library has a 2.11.0 release on Maven Central and a longer feature list in production use. So the comparison is not better versus worse; it is a mature library on a Java foundation versus an incomplete one on a Kotlin foundation. If you need advertising or device mocking today, neither the feature list here nor the readiness note there gives you a production answer, and you would be building that yourself.

Licence, maintenance and upgrade cost

The repository is licensed under BSD-3-Clause. That is a permissive licence: it allows use in closed-source products and requires retaining the copyright notice and disclaimer. It does not carry the patent grant language of Apache 2.0, and it does not impose the source-disclosure obligations of a copyleft licence. This is a description of the licence text, not legal advice; the LICENSE file in the repository is the authoritative document and your own counsel should review it if the distinction matters to you.

The repository is not archived, and the last push was on 2026-07-10, which is recent enough that the project is not dormant. The most recent release listed is 2.11.0, dated 2025-09-11, followed by 2.10.2 and 2.10.1 earlier in 2025. The gap between the last push and the last tagged release suggests ongoing work that has not yet been cut as a version, but the release list is the only evidence available for that.

Upgrade cost has two components. Within the 2.x line, the library has accumulated deprecations rather than removals: getGattCallback() was deprecated in version 2.6 in favour of moving the inner methods onto BleManager, FORMAT_xxx constants were deprecated in favour of FORMAT_xxx_LE in version 2.4, and the ble-livedata module was migrated to Java with API changes because sealed classes were no longer available. Those are the kinds of changes that touch call sites but not architecture. The larger cost is the eventual move to the Kotlin library, which the README states is not backward compatible. That is a rewrite of your BLE layer, not a version bump, and it is worth sizing before you build a large amount of peripheral logic on top of BleManager.

Editorial conclusion

Adopt Android-BLE-Library if your app talks GATT to a known peripheral or acts as a GATT server, and you want the request queue, MTU negotiation, long-packet splitting and error handling handled for you rather than reimplemented per project. Do not adopt it if your main need is scanning: the README states the library does not provide scanning support and points to the separate Android Scanner Compat Library. Do not adopt it either if you want the Kotlin, Flow-based API as your long-term base, since Nordic is building the Kotlin BLE Library 2.0 to replace this one and states that version is not backward compatible with this library. Before committing, verify three things against your own build: that your compile options are set to Java 17, since version 2.7 migrated the library to Java 17, that your target devices behave under the operation timeouts you configure for connect, disconnect and wait-for-notification, and whether the reflection-based cache refresh and bond removal are acceptable in your app, because those two features depend on non-public APIs.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. nordicsemi/Android-BLE-Library on GitHub
4. README
5. Releases