# BLESSED gives Android BLE the shape iOS developers already know > blessed-android is a Java Bluetooth Low Energy library for Android 5 and later that wraps the GATT stack, queues commands, handles bonding and threading, and lets you act as a peripheral as well as a central. A Kotlin rewrite exists alongside it. **weliem/blessed-android** — BLESSED, a Bluetooth Low Energy (BLE) library for Android - Repository: https://github.com/weliem/blessed-android - Stars: 595 · Forks: 124 - Language: Java - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/weliem-blessed-android ## A compact wrapper over the GATT stack, and the problems it removes BLESSED is described as a very compact Bluetooth Low Energy library for Android 5 and higher that makes working with BLE on Android very easy. The README then lists the things it takes care of so you do not have to. Queueing commands, so you do not have to wait for the completion of one command before issuing the next. Bonding correctly, so you do not have to do anything to bond devices reliably. Easy scanning, so you do not have to set up complex scan filters. Managing threading, so you do not have to worry about which thread issues commands or receives results. Being threadsafe, so you do not see weird threading related issues. Workarounds for some known Android bugs, so you do not have to research them. Higher abstraction methods for convenience. And support for multiple simultaneous connections. That list is the honest measure of the package. It is not a different Bluetooth stack, it is a layer that makes the Android one usable, and each item above corresponds to a class of bug that BLE development on Android is known for. The primary language is Java, and the README says the library is written in Java but has been optimized for Kotlin as well, with all types correct in nullability when you use it from Kotlin. The licence is MIT, with the text in the LICENSE file, and the repository is not archived, with the last push on 2026-05-12 and release v2.5.3 on the same day. ## Five classes, and a peripheral you host yourself The library is described as consisting of five core classes and their callback abstract classes, and the list is short enough to memorise. BluetoothCentralManager with BluetoothCentralManagerCallback is used to scan for devices and manage connections. BluetoothPeripheral with BluetoothPeripheralCallback is a replacement for the standard Android BluetoothDevice and BluetoothGatt classes, wrapping all GATT related peripheral functionality. BluetoothPeripheralManager with BluetoothPeripheralManagerCallback is used to create your own peripheral running on an Android phone, where you can add services, control advertising and deal with requests from remote centrals, which are represented by the BluetoothCentral class. And BluetoothBytesParser is a utility class that makes parsing byte arrays easy, and which you can also use to construct your own byte arrays by adding integers, floats or strings. That third one is the most distinctive. Most BLE libraries are about talking to a sensor or a beacon. This one also lets the phone be the device, and the README points at a separate guide, SERVER.md, for creating your own peripheral. The inspiration is stated plainly. BLESSED was inspired by CoreBluetooth on iOS and provides the same level of abstraction, but it stays true to Android by keeping most methods the same and letting you work with the standard classes for Services, Characteristics and Descriptors. If you have developed with CoreBluetooth, the README says you can very easily port your code to Android using this library. There is also a Linux sibling, blessed-bluez, mentioned in the README for the same library on that platform. ## Scanning: four ways, and only one at a time The BluetoothCentralManager class has several scanning methods, and the README lists all of them. ```java public void scanForPeripherals() public void scanForPeripheralsWithServices(UUID[] serviceUUIDs) public void scanForPeripheralsWithNames(String[] peripheralNames) public void scanForPeripheralsWithAddresses(String[] peripheralAddresses) public void scanForPeripheralsUsingFilters(List filters) ``` They work the same way, taking an array of either service UUIDs, peripheral names or MAC addresses, and the last one takes your own list of ScanFilter objects, where the README points at the Android documentation for how those work. When a peripheral is found you get a callback on onDiscoveredPeripheral with the BluetoothPeripheral object and a ScanResult object containing the scan details. Here is the README's example, scanning for the blood pressure service and connecting to what it finds. ```java private final BluetoothCentralManagerCallback bluetoothCentralManagerCallback = new BluetoothCentralManagerCallback() { @Override public void onDiscoveredPeripheral(BluetoothPeripheral peripheral, ScanResult scanResult) { central.stopScan(); central.connectPeripheral(peripheral, peripheralCallback); } }; // Create BluetoothCentral and receive callbacks on the main thread BluetoothCentralManager central = new BluetoothCentralManager(getApplicationContext(), bluetoothCentralManagerCallback, new Handler(Looper.getMainLooper())); // Define blood pressure service UUID UUID BLOODPRESSURE_SERVICE_UUID = UUID.fromString("00001810-0000-1000-8000-00805f9b34fb"); // Scan for peripherals with a certain service UUID central.scanForPeripheralsWithServices(new UUID[]{BLOODPRESSURE_SERVICE_UUID}); ``` The note at the end of that section is a constraint worth internalising: only one of these four types of scans can be active at one time, so you have to call stopScan() before calling another scan. The example does exactly that inside the discovery callback, before connecting. Also note the third argument to the manager constructor. You pass a Handler, and the callbacks arrive on the thread that handler is bound to, here the main thread. That is the threading management the feature list promises, expressed as one constructor argument. ## Three connection methods with different rules There are three ways to connect to a device, and the README explains each one, because the rules differ in a way that matters under load. ```java public void connectPeripheral(BluetoothPeripheral peripheral, BluetoothPeripheralCallback peripheralCallback) public void autoConnectPeripheral(BluetoothPeripheral peripheral, BluetoothPeripheralCallback peripheralCallback) public void autoConnectPeripheralsBatch(Map batch) ``` connectPeripheral tries to connect immediately to a device that has already been found through a scan. It times out after 30 seconds or less depending on the device manufacturer, and there can be only one outstanding connectPeripheral, so if it is called multiple times only one succeeds. autoConnectPeripheral is for re-connecting to known devices whose MAC address you already know. The BLE stack connects automatically when it sees the device in its internal scan, so it may take longer, but the call never times out. The README also says this call will work when the device is not cached by the Android stack, because BLESSED takes care of it, and that unlike connectPeripheral there can be multiple outstanding autoConnectPeripheral requests. autoConnectPeripheralsBatch reconnects to multiple peripherals in one go. The README explains why it exists: since the normal autoConnectPeripheral may involve scanning, if peripherals are uncached it is not suitable for calling very frequently. So the pattern is a division of labour. Immediate connect for a device you are holding in your hand, auto connect for a fleet of known devices, and the batch call when you have many and want one call. ## Peripheral mode, which is where this library differs from most Most Android BLE libraries stop at being a client. BLESSED also covers the server role, through the BluetoothPeripheralManager class. The README describes it as being used to create your own peripheral running on an Android phone, where you can add a service, control advertising and deal with requests from remote centrals, which are represented by the BluetoothCentral class. There is a separate guide in the repository, SERVER.md, for creating your own peripheral. This is the piece that makes the package a two-sided toolkit. A phone that can advertise a GATT service and serve characteristic reads and writes is not just a client, and with the BluetoothBytesParser utility for assembling and reading byte arrays, the whole path from a remote central to a byte array in your app is covered. The BluetoothBytesParser class is worth a second look, because it works in both directions. The README says it makes parsing byte arrays easy, and that you can also use it to construct your own byte arrays by adding integers, floats or strings. For a protocol that mixes a service UUID, a command byte, a length and a float payload, that saves a lot of hand written offset arithmetic, and it does it in a way that is symmetric with the reading side. The callbacks in this half of the library follow the same pattern as the central half, with a BluetoothPeripheralManagerCallback abstract class, so the shape of your code stays consistent whichever role you are playing. ## Distribution through JitPack, and a Kotlin version to prefer The README carries a JitPack badge for weliem/blessed-android, with a monthly downloads counter, and the repository has a jitpack.yml file at the top level, so the distribution route is JitPack building the library from the repository rather than a package published to a standard repository. The build itself is Gradle, with build.gradle, settings.gradle, a gradle.properties, the gradlew wrapper and an app/ directory alongside the blessed/ module that holds the library. There is a GitHub Actions workflow for the Android build, and a docs/ directory in the tree. The more important fact for anyone starting today is in the Update! section at the top of the README: a Kotlin version of the library is available, at the blessed-kotlin repository. The author is signalling that the Kotlin line is where new work is going. That does not make the Java version obsolete. The Java version is the original, and for a project that has to support Android 5 and higher, or that is written in Java, it remains the answer. But a team starting a new Android BLE project today, in Kotlin, is choosing between two libraries and one of them is explicitly recommended by the other. The MIT licence means neither version is a problem for commercial use. ## What BLESSED does not do, and the limits in the README There are honest limits here, and the README states them. The library does not abstract away the Bluetooth stack. It stays true to Android by keeping most methods the same and letting you work with the standard Android classes for Services, Characteristics and Descriptors, so you still need to understand GATT concepts to use it well. It removes the lifecycle and threading pain, not the protocol. The concurrency rules are real constraints rather than internal details. One active scan type at a time. One outstanding connectPeripheral at a time. These are documented in the README with an explicit note, and they are the kind of thing that turns into a support question if you do not read them. The 30 second timeout on connectPeripheral is described as 30 seconds or less depending on the device manufacturer, so behaviour is not uniform across hardware. That is an Android BLE reality rather than a library choice, but it is a thing your error handling has to accommodate. Finally, the project is Android only in this repository, and the Linux version is a separate project, blessed-bluez. Anyone expecting a cross platform BLE layer should look at those two projects side by side rather than assuming one API covers both. ## Conclusion Adopt BLESSED if you are writing an Android app that talks to BLE peripherals and you are tired of the raw BluetoothGatt lifecycle, the bonding edge cases and the callback threading rules. Do not adopt it if you are on Kotlin and starting fresh, because the README points to blessed-kotlin as the current line, and do not expect it to hide the BLE stack, since the design deliberately keeps the standard Android service, characteristic and descriptor classes. Before you commit, check the connectPeripheral and autoConnectPeripheral rules in the README, because only one outstanding immediate connect is allowed at a time, and confirm the Android version range you must support. ## FAQ ### What does the BLESSED Android library handle for me? The README lists command queueing, bonding correctly, easy scanning without complex scan filters, threading management, thread safety, workarounds for known Android bugs, higher abstraction methods, and support for multiple simultaneous connections. ### What is the difference between connectPeripheral and autoConnectPeripheral in BLESSED? connectPeripheral connects immediately to a device already found by a scan, times out after 30 seconds or less depending on the manufacturer, and allows only one outstanding call. autoConnectPeripheral is for known devices by MAC address, never times out, and allows multiple outstanding requests. ### Can I create a BLE peripheral with the BLESSED library? Yes. The BluetoothPeripheralManager class is used to create your own peripheral running on an Android phone, where you can add services, control advertising and handle requests from remote centrals, and the repository has a separate SERVER.md guide on that. ### Is there a Kotlin version of the BLESSED Android library? Yes, the README points to blessed-kotlin as a Kotlin version of the library. BLESSED itself is written in Java and says it has been optimized for Kotlin with correct nullability types. ### Which Android versions does BLESSED support? The README describes BLESSED as a Bluetooth Low Energy library for Android 5 and higher. A separate project, blessed-bluez, provides the library for Linux. ## Sources - [Issues](https://github.com/weliem/blessed-android/issues) - [License: MIT](https://github.com/weliem/blessed-android/blob/master/LICENSE) - [README](https://github.com/weliem/blessed-android/blob/master/README.md) - [Releases](https://github.com/weliem/blessed-android/releases) - [weliem/blessed-android on GitHub](https://github.com/weliem/blessed-android) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/weliem-blessed-android