{"id":13657982,"url":"https://github.com/NordicSemiconductor/Android-BLE-Library","last_synced_at":"2025-04-24T08:31:00.206Z","repository":{"id":37706224,"uuid":"114649434","full_name":"NordicSemiconductor/Android-BLE-Library","owner":"NordicSemiconductor","description":"A library that makes working with Bluetooth LE on Android a pleasure. Seriously.","archived":false,"fork":false,"pushed_at":"2025-03-06T13:03:30.000Z","size":3114,"stargazers_count":2141,"open_issues_count":40,"forks_count":431,"subscribers_count":65,"default_branch":"main","last_synced_at":"2025-04-10T14:11:24.214Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NordicSemiconductor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-18T14:17:43.000Z","updated_at":"2025-04-10T10:30:32.000Z","dependencies_parsed_at":"2024-04-29T11:24:33.655Z","dependency_job_id":"9f8ce891-6dc8-4eda-b968-173a92927064","html_url":"https://github.com/NordicSemiconductor/Android-BLE-Library","commit_stats":null,"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2FAndroid-BLE-Library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2FAndroid-BLE-Library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2FAndroid-BLE-Library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NordicSemiconductor%2FAndroid-BLE-Library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NordicSemiconductor","download_url":"https://codeload.github.com/NordicSemiconductor/Android-BLE-Library/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250591934,"owners_count":21455466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T05:00:54.776Z","updated_at":"2025-04-24T08:31:00.190Z","avatar_url":"https://github.com/NordicSemiconductor.png","language":"Java","funding_links":[],"categories":["Android"],"sub_categories":["Android libraries"],"readme":"[ ![Download](https://maven-badges.herokuapp.com/maven-central/no.nordicsemi.android/ble/badge.svg?style=plastic) ](https://search.maven.org/artifact/no.nordicsemi.android/ble)\n\n# Android BLE Library\n\nAn Android library that solves a lot of Android's Bluetooth Low Energy problems.\n\n\u003e [!Note]\n\u003e We're working on a new version of Bluetooth LE library, which eventually will replace this one:\n\u003e [Kotlin BLE Library / version 2.0](https://github.com/NordicSemiconductor/Kotlin-BLE-Library/tree/version/2.0).\n\u003e Mind, that version 2 is not backward compatible version 1 or with this library.\n\u003e\n\u003e Currently, the library is in the early development stage. It is not recommended for production use,\n\u003e but we encourage you to try it out and provide feedback.\n\u003e\n\u003e The new library offers the following improvements over this one:\n\u003e  * 100% Kotlin code\n\u003e  * Scanning for Bluetooth LE devices (scan results as `Flow`)\n\u003e  * Support for Bluetooth LE advertising\n\u003e  * Support for mocking BLE devices (easy testing)\n\u003e  * All BLE operations use `suspend` modifier or `Flow`s\n\u003e\n\u003e Read more on project's Readme file.\n\n## Importing\n\nThe library may be found on Maven Central repository.\nAdd it to your project by adding the following dependency:\n\n```groovy\nimplementation 'no.nordicsemi.android:ble:2.10.0'\n```\nThe last version not migrated to AndroidX is 2.0.5.\n\nBLE library with Kotlin extension is available in:\n```groovy\nimplementation 'no.nordicsemi.android:ble-ktx:2.10.0'\n```\n\nTo import the BLE library with set of parsers for common Bluetooth SIG characteristics, use:\n```groovy\nimplementation 'no.nordicsemi.android:ble-common:2.10.0'\n```\nFor more information, read [this](BLE-COMMON.md).\n\nAn extension for easier integration with `LiveData` is available after adding:\n```groovy\nimplementation 'no.nordicsemi.android:ble-livedata:2.10.0'\n```\nThis extension adds `ObservableBleManager` with `state` and `bondingState` properties, which\nnotify about connection and bond state using `androidx.lifecycle.LiveData`.\n\n\u003cdetails\u003e\n\t\u003csummary\u003eImporting as a module\u003c/summary\u003e\n\nClone this project and add it to your project:\n\n1. In *settings.gradle* file add the following lines:\n    ```groovy\n    if (file('../Android-BLE-Library').exists()) {\n        includeBuild('../Android-BLE-Library')\n    }\n    ```\n2. Sync project and build it.\n\n   The library uses Java 1.18 features. If you're using Android Studio below Giraffe, make sure your\n   *build.gradle* includes the following configuration:\n\n   ```groovy\n       compileOptions {\n           sourceCompatibility JavaVersion.VERSION_1_17\n           targetCompatibility JavaVersion.VERSION_1_17\n       }\n       // For Kotlin projects additionally:\n       kotlinOptions {\n           jvmTarget = \"1.17\"\n       }\n    ```\n\u003c/details\u003e\n\n## Features\n\n**BleManager** class provides the following features:\n\n1. Connection, with automatic retries\n2. Service discovery\n3. Bonding (optional) and removing bond information (using reflections)\n4. Automatic handling of Service Changed indications\n5. Device initialization\n6. Asynchronous and synchronous BLE operations using queue\n7. Splitting and merging long packets when writing and reading characteristics and descriptors\n8. Requesting MTU and connection priority (on Android Lollipop or newer)\n9. Reading and setting preferred PHY (on Android Oreo or newer)\n10. Reading RSSI\n11. Refreshing device cache (using reflections)\n12. Reliable Write support\n13. Operation timeouts (for *connect*, *disconnect* and *wait for notification* requests)\n14. Error handling\n15. Logging\n16. GATT server (since version 2.2)\n17. Kotlin support (coroutines, Flow, ...) (since version 2.3)\n\n\u003e Note:\n  The library **does not provide support for scanning** for Bluetooth LE devices.\n  Instead, we recommend using\n  [Android Scanner Compat Library](https://github.com/NordicSemiconductor/Android-Scanner-Compat-Library)\n  which brings almost all recent features, introduced in Lollipop and later, to the older platforms.\n\n### Recent changes\n\nSee [Releases](https://github.com/NordicSemiconductor/Android-BLE-Library/releases) for details.\nBelow is short summary:\n\n\u003cdetails\u003e\n\t\u003csummary\u003eVersion 2.7\u003c/summary\u003e\n\n1. Library has been migrated to Java 17 due to minimum supported version in Android Studio Giraffe.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\t\u003csummary\u003eVersion 2.6\u003c/summary\u003e\n\n1. `getGattCallback()` method has been deprecated. Instead, simply move the inner methods to the\n   `BleManager` class. See [this PR](https://github.com/NordicSemiconductor/Android-nRF-Blinky/pull/78).\n2. Support for *server only* implementation using `attachClientConnection(BluetoothDevice)`. Call it instead of\n   `connect(BluetoothDevice)` to use the device as server-only.\n3. Data provider for read requests (server side) was added.\n4. Cancellation support for flows and suspended methods added to `:ble-kts`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\t\u003csummary\u003eVersion 2.4\u003c/summary\u003e\n\n1. More `:ble-ktx` extensions.\n\t1. `.suspendForResponse()` and `.suspendForValidResponse()` extension methods added to read and write requests.\n\t2. `.asResponseFlow()` and `.asValidResponseFlow()` methods added to `ValueChangedCallback`.\n\t3. `.stateAsFlow()` and `.bondingStateAsFlow()` in `BleManager` now return the same flow when called multiple times.\n\t4. Progress indications for split outgoing data and merged incoming data can be observed as `Flow` using\n\t   `splitWithProgressFlow(...)` and `mergeWithProgressFlow(...)`.\n2. A new `then(...)` method added to `ValueChangedCallback` which will be called when the callback has been unregistered,\n   or the device has invalidated services (i.e. it has disconnected). Useful to release resources.\n3. A new option to remove a handler from each `Request` using `setHandler(null)`, which will make the callbacks\n   called immediately from the worker looper.\n4. Option to filter logs by priority. By default only logs on `Log.INFO` or higher will now be logged. Use\n   `getMinLogPriority()` to return a different value if needed. Logs with lower priority will not be produced\n   at all, making the library less laggy (parsing incoming data to hex takes notable time).\n5. Added support for Big Endian format types with the new `Data.FORMAT_xxx_BE` types. Also, `FORMAT_xxx` have been\n   deprecated in favor of `FORMAT_xxx_LE`.\n6. All user callbacks (`before`, `with`, `then`, `fail`, ...) are now wrapped in `try-catch` blocks.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\t\u003csummary\u003eVersion 2.3\u003c/summary\u003e\n\n1. `:ble-ktx` module added with support for coroutines and Flow.\n\t1. `.suspend()` methods added in `Request`s.\n\t2. `asFlow()` method added to `ValueChangedCallback`.\n\t3. Connection and bonding state available as Flow.\n\t4. New helper methods to get a `BluetoothGattCharacteristic` with given required properties\n\t   and instance id added to `BluetoothGattService`.\n2. `JsonMerger` class added, which should help with use cases when a device sends a JSON file in multiple\n\tpackets.\n3. `:ble-livedata` migrated to Java with some API changes, as sealed classes are no longer available.\n4. Support for new `onServicesChanged()` callback, added in API 31 (Android 12).\n5. Option to cancel pending Bluetooth LE connection using `ConnectRequest.cancelPendingConnection()`.\n\n    When using coroutines, use `.suspend()` method in `Request`, instead of `enqueue()` or `await()`.\n\n    To register to notifications and indications (or incoming write requests for server) use\n    ```kotlin\n    setNotificationCallback(characteristic)\n       .merge(JsonMerger()) // Example of how to use JsonMerger, optional\n       .asFlow()\n    ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\t\u003csummary\u003eVersion 2.2\u003c/summary\u003e\n\n1. GATT Server support. This includes setting up the local GATT server on the Android device, new\n   requests for server operations:\n   * *wait for read*,\n   * *wait for write*,\n   * *send notification*,\n   * *send indication*,\n   * *set characteristic value*,\n   * *set descriptor value*.\n2. New conditional requests:\n   * *wait if*,\n   * *wait until*.\n3. BLE operations are no longer called from the main thread.\n4. There's a new option to set a handler for invoking callbacks. A handler can also be set per-callback.\n\nVersion 2.2 breaks some API known from version 2.1.1.\nCheck out [migration guide](MIGRATION.md).\n\u003c/details\u003e\n\n## Usage\n\nSee [Usage](USAGE.md) for more details.\n\n## Examples\n\n#### Trivia game\n\nThe [Trivia game](https://github.com/NordicSemiconductor/Android-BLE-Library/tree/main/examples/trivia)\nis an example demonstrating client and server.\n\n#### GATT Client Example\n\nPlease refer to the `examples/ble-gatt-client folder` for a project that illustrates the GATT\nserver provided as a foreground service. There's a simple UI with a text field to update\nwith the value of a characteristic that can be read and subscribed to. This characteristic also\ndemands encryption as an illustration of best-practice.\n\nYou can run this client on one device and a complimenting server on another (see the next section).\n\n\u003e Note:\n  This project is not maintained actively. It is provided as an example only and may not be\n  migrated to latest version.\n\n#### GATT Server example\n\nStarting from version 2.2 you may now define and use the GATT server in the BLE Library.\n\nPlease refer to the `examples/ble-gatt-server folder` for a project that illustrates the GATT\nserver provided as a foreground service. There's a simple UI with a text field to update\nthe value of a characteristic that can be read and subscribed to. This characteristic also\ndemands encryption as an illustration of best-practice.\n\n\u003e Note:\n  This project is not maintained actively. It is provided as an example only and may not be\n  migrated to latest version.\n\n#### More examples\n\nFind the simple example here [Android nRF Blinky](https://github.com/NordicSemiconductor/Android-nRF-Blinky).\n\nFor an example how to use it from a `ViewModel` or a `Service`, check\n[nRF Toolbox](https://github.com/NordicSemiconductor/Android-nRF-Toolbox).\n\n## Version 1.x\n\nThe BLE library v 1.x is no longer supported. Please migrate to 2.x for bug fixing releases.\nFind it on [version/1x branch](https://github.com/NordicSemiconductor/Android-BLE-Library/tree/version/1x).\n\nA migration guide is available [here](MIGRATION.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNordicSemiconductor%2FAndroid-BLE-Library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNordicSemiconductor%2FAndroid-BLE-Library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNordicSemiconductor%2FAndroid-BLE-Library/lists"}