# Background

The best resources for those new to Bluetooth Low Energy on the Android platform.

- [Android Lollipop: Bluetooth LE Matures](https://www.youtube.com/watch?v=qx55Sa8UZAQ) - A nice overview video by Dave Smith. 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

- [iDevicesInc/SweetBlue](https://github.com/iDevicesInc/SweetBlue/) - A proprietary library that abstracts away many of Android BLE challenges. May be useful if you have more dollars than time, or if you are developing stability-critical applications.
- [Polidea/RxAndroidBle](https://github.com/Polidea/RxAndroidBle) - A reactive BLE wrapper, useful for one-shot connections and operations (is not set up to support persistent connections).
- [douglasjunior/AndroidBluetoothLibrary](https://github.com/douglasjunior/AndroidBluetoothLibrary) - MIT-licensed Android BLE wrapper. I haven't personally used this, but it looks good.

# 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](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!
- Erik Hellman's in-progress blog post series ([part 1](https://hellsoft.se/bluetooth-low-energy-on-android-part-1-1aa8bf60717d)) ([part 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/puck-central-android](https://github.com/NordicSemiconductor/puck-central-android) - Source code for an Android app associated with Nordic Semiconductor's [Puck platform](http://nordicsemiconductor.github.io/puck/). This implementation is pretty complete. In particular the serial operations logic within the [operations types](https://github.com/NordicSemiconductor/puck-central-android/tree/master/PuckCentral/app/src/main/java/no/nordicsemi/puckcentral/bluetooth/gatt/operations) and [operation manager implementation](https://github.com/NordicSemiconductor/puck-central-android/blob/master/PuckCentral/app/src/main/java/no/nordicsemi/puckcentral/bluetooth/gatt/GattManager.java) includes several optional but valuable refinements.
- [googlesamples/android-BluetoothLeGatt](https://github.com/googlesamples/android-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 his 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.
- [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

- [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.