Android Bluetooth Low Energy (BLE) Resources

android-bluetooth-low-energy-resources.md

Background

Platform-Agnostic

• "Introduction to Bluetooth Low Energy" by Adafruit.

Android-Specific

• "Android Lollipop: Bluetooth LE Matures" (video).
• "Bluetooth (LE) with Dave (devunwired) Smith" (podcast).
• "State of BLE on Android in 2022" (slides, video).

Libraries

• NordicSemiconductor/Android-BLE-Library - Contains production-ready implementations of many of the important components (queues, managers, etc.) for working with BLE on Android. Consider using this library as-is or browsing the source code as inspiration if building your own implementation.
• Polidea/RxAndroidBle - For using RxJava with BLE.
• Beepiz/BleGattCoroutines - For using Kotlin's coroutines to sidestep BLE callback hell.
• HubbellCorp/SweetBlue.
• douglasjunior/AndroidBluetoothLibrary.
• JuulLabs/kable - Coroutines-based Kotlin Multiplatform library.
• ErikHellman/android-blex.

Building

Resources relevant to building Bluetooth Low Energy Android applications from scratch.

In-Depth Guides

• "Bluetooth Low Energy on Android: Top Tips For The Tricky Bits" (slides, video) by Stuart Kent - My own talk, but now several years old.
• "The Ultimate Guide to Android Bluetooth Low Energy" by PunchThrough - A very modern (2020) comprehensive guide.
• "Bluetooth LE for modern Android Development" series (part 1, part 2, part 3) by Erik Hellman - Articles with advice that's particularly relevant in 2022.
• Android BLE Issues - A fairly complete list of symptoms you are likely to encounter while working with Android's BLE stack. Some apply to pre-Lollipop only, but many still exist and occur.

Implementations

• PunchThrough/ble-starter-android - Source code accompanying the PunchThrough guide listed above.
• NordicSemiconductor/Android-nRF-Blinky - Source code for an Android app that uses Nordic Semiconductor's Android-BLE-Library.
• android/connectivity-samples (BluetoothLeGatt) - A compact Service and broadcast based example.

Android Source Code

• Locations within the AOSP source code where GATT success and error codes are defined:
  • Lollipop
  • Marshmallow and later (verified location through 8.0.0)

Stack Overflow

Useful users, questions, answers, and comments from Stack Overflow's Q&A.

• Emil - A user who consistently provides high-quality and detailed information regarding BLE on Android. Worth browsing their answers!
• "Android 4.3 Bluetooth Low Energy unstable" - In particular, this answer is a great overview and includes a hint regarding Wi-Fi/BLE interactions that I haven't seen elsewhere.
• "How to detect Bluetooth state change using a broadcast receiver?"
• "Difference between close() and disconnect() in Android Bluetooth API?"
• "Android - Could not connect to bluetooth device on Lollipop" - This answer provides some tips regarding the transport type flag passed to BluetoothDevice.connectGatt.
• "Android Bluetooth LE: Not discovering services after connection" - This comment indicates that one should delay calls to BluetoothGatt.close until either (1) disconnection completes, or (2) a predefined period of time elapses.
• "How to programmatically force bluetooth low energy service discovery on Android without using cache" - This answer formed the basis of my refined service cache-clearing method.
• "Android 4.3: How to connect to multiple Bluetooth Low Energy devices" - This answer discusses the serial nature of the Bluetooth APIs and indicates that things work the same for web and iOS.
• "Android BLE API: GATT Notification not received"
• "RxAndroidBle keeping a persistant connection + Write/Notification handling" - This answer confirms that RxAndroidBle was not designed to accommodate persistent connections. UPDATE: apparently this is possible; see author's tweet here.
• "Location requirement to scan for BLE devices" - This answer provides some context regarding the location permission requirement for scanning.
• "Is the native Android BLE implementation synchronous in nature?" - This answer confirms (from a Samsung perspective) that BLE operations should be performed serially.
• "clientIf field in Android BluetoothGatt class" - Some information on the clientIf value that's logged with almost all Android BLE calls.
• "Why does setCharacteristicNotification() not actually enable notifications?"
• "Android Bluetooth Low Energy Characteristic notification count limit: does this vary by device?" - Clarification that the stack's 15 characteristic notifications limit is a limit per peripheral/server rather than per central/client/mobile device.

Google Issues

(You must sign in with a Google account to access these.)

• "Android 4.3: Bluetooth LE pretty instable"
• "NullPointerException in BluetoothGatt.java when disconnecting and closing" - Includes discussion regarding exactly when BluetoothGatt.disconnect and BluetoothGatt.close should be called.
• "Emulator and Bluetooth" - Requests the addition of Bluetooth support to Android emulators (via host device Bluetooth).
• "Bluetooth permission request dialog" - Bug report related to weird window pop-up while programmatically prompting user to enable Bluetooth.
• "Get BLE scan result using 'BluetoothLeScanner.startScan' must open Location Service in Android 6.0" - Long thread related to location permissions and services requirements.
• "[BLE] Android does not discover services if device supports Service Changed" - Thread related to service caching and how to skip the cache.

Here is a more complete version of the code that does not produce any result, nor any error. The callback is just never called.

bluetoothAdapter?.bluetoothLeScanner?.startScan(
    arrayListOf(ScanFilter.Builder().setServiceUuid(ParcelUuid(UUID.fromString("00004865-726f-6e54-7261-636b2d475053"))).build()),
    scanSettingsBuilder.build(),
    leScanCallback
)

I see you asked a question over at SO; I'll respond there (https://stackoverflow.com/questions/58731684/scanning-for-ble-peripherals-with-a-scan-filter-based-on-advertised-service-uuid).

@ret394 thanks for the note; I added a comment about signing in to the Google issues links.

any future considerations for adding documentation for the DeviceCompanion API that targets api 26 or higher?

@comann unfortunately I haven't worked with Bluetooth for many years, and have no plans to do so in the near future :(. The new APIs you mention look interesting but also appear to operate at a higher level of abstraction than the APIs documented here. I would probably recommend creating a separate document if you are looking to collect resources on them specifically.

Do you have the Qualcomm CSR BLE ?

Not sure what you're asking, sorry John! So the answer is probably: no :)

Not sure what you're asking, sorry John! So the answer is probably: no :)

Ouch , Thanks Anyway :)

please help me solving GATT_ERROR 133.
I am stock here and can't go ahead.
It shows 7times outof 10.
specifically number of times decreases or increased according to phone models.

Thanks in advance