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.

I faced this issue, BLE scan is not working when screen is off on Android 9.0 and above

@harishankar-jayasakthi do you have location permission granted at all times (not just while app is in use/in the foreground)? Just a guess!

When I scan for BLE peripherals without any filter, I see my custom peripheral, but the moment I add a scan filter like the following, I don't see it anymore:

bluetoothAdapter?.bluetoothLeScanner?.startScan(
                arrayListOf(ScanFilter.Builder().setServiceUuid(MY_SERVICE_UUID).build()),
                scanSettingsBuilder.build(),
                leScanCallback
            )

And yet in nrfConnect, I can see the following advertisement data for my BLE peripheral:

Click for image

And of course, the MY_SERVICE_UUID constant matches the service UUID in the screenshot.
Plus, I'm working now on the Android port of an iOS application that scans for BLE devices with the same kind of filters and it works.
How do scan filters work exactly? What is the requirement for a peripheral to be accepted by such a filter?

Hmm, odd. Does MY_SERVICE_UUID contain the full UUID, not just a custom portion? Do you receive anything in the scan callback, or an error, or just nothing at all?

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