# Background

## Platform-Agnostic

- "[Introduction to Bluetooth Low Energy](https://learn.adafruit.com/introduction-to-bluetooth-low-energy/introduction)" by Adafruit.

## Android-Specific

- "[Android Lollipop: Bluetooth LE Matures](https://www.youtube.com/watch?v=qx55Sa8UZAQ)" - A nice overview video by [Dave Smith](https://twitter.com/devunwired). Focuses on Lollipop and newer.
- Fragmented Episode 45: "[Bluetooth (LE) with Dave (devunwired) Smith](http://fragmentedpodcast.com/episodes/45/)" - Another great Dave Smith overview if you prefer the podcast format!

# Libraries

- [NordicSemiconductor/Android-BLE-Library](https://github.com/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](https://github.com/Polidea/RxAndroidBle) - For using RxJava with BLE.
- [Beepiz/BleGattCoroutines](https://github.com/Beepiz/BleGattCoroutines) - For using Kotlin's coroutines to sidestep BLE callback hell.
- [iDevicesInc/SweetBlue](https://github.com/iDevicesInc/SweetBlue/) (proprietary) - May be useful if you have more dollars than time, or if you are developing stability-critical applications.
- [douglasjunior/AndroidBluetoothLibrary](https://github.com/douglasjunior/AndroidBluetoothLibrary).

# 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" by [Stuart Kent](https://twitter.com/skentphd) ([slides](https://speakerdeck.com/stkent/bluetooth-low-energy-on-android-top-tips-for-the-tricky-bits-video), [video](https://www.youtube.com/watch?v=jDykHjn-4Ng)) - My own talk!
- "Bluetooth Low Energy on Android" series by [Erik Hellman](https://twitter.com/ErikHellman) ([post 1](https://hellsoft.se/bluetooth-low-energy-on-android-part-1-1aa8bf60717d)) ([post 2](https://hellsoft.se/bluetooth-low-energy-on-android-part-2-8fdb8ee3bfe9)) - Comprehensive introductory articles.
- [Android BLE Issues](https://github.com/iDevicesInc/SweetBlue/wiki/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

- [NordicSemiconductor/Android-nRF-Blinky](https://github.com/NordicSemiconductor/Android-nRF-Blinky) - Source code for an Android app that uses Nordic Semiconductor's [Android-BLE-Library](https://github.com/NordicSemiconductor/Android-BLE-Library/).
- [android/connectivity-samples (BluetoothLeGatt)](https://github.com/android/connectivity-samples/tree/master/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](https://android.googlesource.com/platform/external/bluetooth/bluedroid/+/android-5.1.1_r38/stack/include/gatt_api.h)
    - [Marshmallow and later (verified location through 8.0.0)](https://android.googlesource.com/platform/system/bt/+/android-6.0.1_r80/stack/include/gatt_api.h)

## Stack Overflow

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

- [Emil](https://stackoverflow.com/users/556495/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](https://stackoverflow.com/questions/17870189/android-4-3-bluetooth-low-energy-unstable)" - In particular, [this answer](https://stackoverflow.com/a/18889509/2911458) 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?](https://stackoverflow.com/questions/24888023/how-to-detect-bluetooth-state-change-using-a-broadcast-receiver)"
- "[Difference between close() and disconnect() in Android Bluetooth API?](https://stackoverflow.com/questions/23110295/difference-between-close-and-disconnect-in-android-bluetooth-api)"
- "[Android - Could not connect to bluetooth device on Lollipop](https://stackoverflow.com/questions/28018722/android-could-not-connect-to-bluetooth-device-on-lollipop)" - [This answer](https://stackoverflow.com/a/29092645/2911458) provides some tips regarding the transport type flag passed to `BluetoothDevice.connectGatt`.
- "[Android Bluetooth LE: Not discovering services after connection](https://stackoverflow.com/questions/24025486/android-bluetooth-le-not-discovering-services-after-connection)" - [This comment](https://stackoverflow.com/questions/24025486/android-bluetooth-le-not-discovering-services-after-connection#comment70743389_24044509) 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](https://stackoverflow.com/questions/22596951)" - [This answer](https://stackoverflow.com/a/22709467/2911458) formed the basis of my refined service cache-clearing method.
- "[Android 4.3: How to connect to multiple Bluetooth Low Energy devices](https://stackoverflow.com/questions/21237093)" - [This answer](https://stackoverflow.com/a/30455650/2911458) 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](https://stackoverflow.com/questions/17910322)"
- "[RxAndroidBle keeping a persistant connection + Write/Notification handling](https://stackoverflow.com/questions/38902913)" - [This answer](https://stackoverflow.com/a/38919653/2911458) confirms that RxAndroidBle was not designed to accommodate persistent connections. UPDATE: apparently this is possible; see author's tweet [here](https://twitter.com/DSeweryn/status/946422910926950400).
- "[Location requirement to scan for BLE devices](https://stackoverflow.com/questions/40186200)" - [This answer](https://stackoverflow.com/a/40187238/2911458) provides some context regarding the location permission requirement for scanning.
- "[Is the native Android BLE implementation synchronous in nature?](https://stackoverflow.com/questions/18011816)" - [This answer](https://stackoverflow.com/a/18054654/2911458) confirms (from a Samsung perspective) that BLE operations should be performed serially.
- "[clientIf field in Android BluetoothGatt class](https://stackoverflow.com/questions/34158315)" - Some information on the `clientIf` value that's logged with almost all Android BLE calls.
- "[Why does setCharacteristicNotification() not actually enable notifications?](https://stackoverflow.com/questions/22817005)"
- "[Android Bluetooth Low Energy Characteristic notification count limit: does this vary by device?](https://stackoverflow.com/questions/42771904)" - 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](https://issuetracker.google.com/issues/36976711)"
- "[NullPointerException in BluetoothGatt.java when disconnecting and closing](https://issuetracker.google.com/issues/37057260)" - Includes discussion regarding exactly when `BluetoothGatt.disconnect` and `BluetoothGatt.close` should be called.
- "[Emulator and Bluetooth](https://issuetracker.google.com/issues/36972875)" - Requests the addition of Bluetooth support to Android emulators (via host device Bluetooth).
- "[Bluetooth permission request dialog](https://issuetracker.google.com/u/2/issues/36979302)" - 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](https://issuetracker.google.com/u/1/issues/37065090)" - Long thread related to location permissions and services requirements.
- "[[BLE] Android does not discover services if device supports Service Changed](https://issuetracker.google.com/u/1/issues/37012916)" - Thread related to service caching and how to skip the cache.