{"id":23141330,"url":"https://github.com/robotpajamas/blueteeth","last_synced_at":"2025-08-17T13:31:43.358Z","repository":{"id":28343807,"uuid":"31857295","full_name":"RobotPajamas/Blueteeth","owner":"RobotPajamas","description":"A simple, lightweight library intended to take away some of the cruft and tediousness of using the Android BLE.","archived":false,"fork":false,"pushed_at":"2020-09-05T02:56:59.000Z","size":463,"stargazers_count":105,"open_issues_count":18,"forks_count":28,"subscribers_count":5,"default_branch":"develop","last_synced_at":"2025-04-05T07:33:04.434Z","etag":null,"topics":["android","android-ble","bluetooth","bluetooth-low-energy","java"],"latest_commit_sha":null,"homepage":"https://www.sureshjoshi.com/mobile/blueteeth-for-android/","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RobotPajamas.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-08T16:48:26.000Z","updated_at":"2025-02-27T07:38:04.000Z","dependencies_parsed_at":"2022-08-25T09:53:55.467Z","dependency_job_id":null,"html_url":"https://github.com/RobotPajamas/Blueteeth","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/RobotPajamas/Blueteeth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobotPajamas%2FBlueteeth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobotPajamas%2FBlueteeth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobotPajamas%2FBlueteeth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobotPajamas%2FBlueteeth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RobotPajamas","download_url":"https://codeload.github.com/RobotPajamas/Blueteeth/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RobotPajamas%2FBlueteeth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270856554,"owners_count":24657688,"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","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["android","android-ble","bluetooth","bluetooth-low-energy","java"],"created_at":"2024-12-17T14:13:29.364Z","updated_at":"2025-08-17T13:31:43.072Z","avatar_url":"https://github.com/RobotPajamas.png","language":"Kotlin","readme":"# Blueteeth\n\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-Blueteeth-blue.svg?style=flat)](http://android-arsenal.com/details/1/3512)\n![!Travis CI build badge](https://travis-ci.org/RobotPajamas/Blueteeth.svg?branch=master)\n\n## What Is Blueteeth?\n\nBlueteeth is a simple, lightweight library intended to take away some of the cruft and tediousness of using the Android BLE API. I wrote about it originally here: [http://www.sureshjoshi.com/mobile/bluetooth-bluetooths-blueteeth/](http://www.sureshjoshi.com/mobile/bluetooth-bluetooths-blueteeth/), with a more recent update at [http://www.sureshjoshi.com/mobile/blueteeth-for-android/](http://www.sureshjoshi.com/mobile/blueteeth-for-android/).\n\nIt was inspired by the simplicity and ease-of-use of [LGBluetooth](https://github.com/l0gg3r/LGBluetooth) on iOS.\n\nThe upcoming iOS companion library is [SwiftyTeeth](https://github.com/RobotPajamas/SwiftyTeeth).\n\n## High-Level\n\nAn underlying motivator of this BLE library was to build something that didn't require platform-specific hacks. \n\nBlueteeth fixes several Android-platform-specific problems, in terms of calls sometimes working and sometimes not. Under the hood, all calls are initiated from the main thread... This pattern helps solve some manufacturer-specific defects in Android BLE implementations ([looking at you, Samsung](https://stackoverflow.com/questions/20069507/gatt-callback-fails-to-register)).\n\nIn the `.connect()` call, I have exposed the autoReconnect parameter which allows an underlying Bluetooth connection to do exactly what it suggests. However, I recommend not using it, and I might remove it entirely. [This StackOverflow post](https://stackoverflow.com/questions/22214254/android-ble-connect-slowly/23749770#23749770) explains it well, but essentially, autoReconnect is a very slow, low-power reconnect... I've noticed it can take a minute or two to actually re-connect, so it doesn't function like most developers would expect.\n\nAdditionally, when you're done with the BlueteethDevice object, call `.close()` on it, in order to free up resources (there is a finalizer on the BlueteethDevice object, but don't rely on it running). Calling `.close()` on the BLE objects is both suggested and required.\n\n## Usage\n\nScan for BLE devices using the BlueteethManager singleton:\n\n```java\nBlueteethManager.with(this).scanForPeripherals(DEVICE_SCAN_MILLISECONDS, blueteethDevices -\u003e {\n    // Scan completed, iterate through received devices and log their name/mac address\n    for (BlueteethDevice device : blueteethDevices) {\n        if (!TextUtils.isEmpty(device.getBluetoothDevice().getName())) {\n            Timber.d(\"%s - %s\", device.getName(), device.getMacAddress());\n        }\n    }\n});\n```\n\nInitiate a connection using a BlueteethDevice:\n\n```java \nmBlueteethDevice.connect(shouldAutoreconnect, isConnected -\u003e {\n    Timber.d(\"Is the peripheral connected? %s\", Boolean.toString(isConnected));\n});\n```\n\nDiscover Bluetooth services and characteristics:\n\n```java \nmBlueteethDevice.discoverServices(response -\u003e {\n    if (response != BlueteethResponse.NO_ERROR) {\n        Timber.e(\"Discovery error - %s\",  response.name());\n        return;\n    }\n    Timber.d(\"Discovered services... Can now try to read/write...\");\n});\n``` \n\nWrite to a connected BlueteethDevice:\n\n```java\nmBlueteethDevice.writeCharacteristic(new byte[]{1, 2, 3, 4}, characteristicUUID, serviceUUID, response -\u003e {\n    if (response != BlueteethResponse.NO_ERROR) {\n        Timber.e(\"Write error - %s\",  response.name());\n        return;\n    }\n    Timber.d(\"Characterisic Written...\");\n})\n```\n\nRead from a connected BlueteethDevice:\n\n```java \nmBlueteethDevice.readCharacteristic(characteristicUUID, serviceUUID, (response, data) -\u003e {\n    if (response != BlueteethResponse.NO_ERROR) {\n        Timber.e(\"Read error - %s\",  response.name());\n        return;\n    }\n    Timber.d(\"Just read the following data... %s\",  Arrays.toString(data));\n});\n```\n\nConvenience methods to connect (if not connected), and read/write... This will NOT automatically disconnect, however, so you will remain disconnected unless you try to disconnect in the callback:\n \n```java\nBlueteethUtils.writeData(new byte[]{1, 2, 3, 4}, characteristicUUID, serviceUUID, mBlueteethDevice, response -\u003e {\n    if (response != BlueteethResponse.NO_ERROR) {\n        Timber.e(\"Write error - %s\",  response.name());\n        return;\n    }\n    Timber.d(\"Connected to and wrote characteristic...\");\n});\n```\n\n```java\nBlueteethUtils.read(characteristicUUID, serviceUUID, mBlueteethDevice, (response, data) -\u003e {\n    if (response != BlueteethResponse.NO_ERROR) {\n        Timber.e(\"Read error - %s\",  response.name());\n        return;\n    }\n    Timber.d(\"Just connected and read the following data... %s\",  Arrays.toString(data));\n});\n```\n\nCheck out the sample app in `blueteeth-sample/` to see the API in action. \n\n\n## Future Directions\n\n### Auto-Reconnect\n\nAs mentioned above, the stack-level auto-reconnect implementation is pretty useless because of how long the reconnect process takes. I might leave the existing API, however, use a different underlying implementation to allow fast(er) reconnects.\n\n### Queues\n\nAs mentioned in [my original Blueteeth blog post](http://www.sureshjoshi.com/mobile/bluetooth-bluetooths-blueteeth/), I hate Callback Hell (or rightward drift), but I haven't yet solved that in this library. The current usage for chaining calls is still, unfortunately, callbacks in callbacks. \n\n### Mocks and Tests\n\nOut-of-band of this repo, I have been working on a small mocking framework to a) allow unit/functional testing of classes that call BlueteethManager (singleton), and b) allow a runtime implementation of Blueteeth, so it can be tested in a simulator, and preloaded with 'fake' results. \n\na) is quick and easy, b) is hard and painful.\n\nI will incorporate that code into this repo when it is stable.\n\n### Reactive Everything!\n\nNow that this library is released and progressively becoming more stable, the next step in the process is to create Reactive bindings (RxAndroid bindings specifically). They will be created in a separate repo, so that there isn't a forced, heavy dependency on the Rx framework in any app that just wants to use Blueteeth.\n\n## Download\n\n```groovy\ncompile 'com.robotpajamas.blueteeth:blueteeth:0.2.0'\n```\n\n## Issues\n\nLastly, I have a few lingering issues that I want to fix in the near future. 1 bug, and a few points just for my sanity: [https://github.com/RobotPajamas/Blueteeth/issues](https://github.com/RobotPajamas/Blueteeth/issues)\n\n## License\n\nThe Apache License (Apache)\n\n    Copyright (c) 2016 Robot Pajamas\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n    SOFTWARE.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotpajamas%2Fblueteeth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobotpajamas%2Fblueteeth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobotpajamas%2Fblueteeth/lists"}