{"id":41185603,"url":"https://github.com/sputnikdev/bluetooth-manager","last_synced_at":"2026-01-22T20:16:09.305Z","repository":{"id":57740849,"uuid":"82150790","full_name":"sputnikdev/bluetooth-manager","owner":"sputnikdev","description":"Java Bluetooth Manager. A library/framework for managing bluetooth adapters, bluetooth devices, GATT services and characteristics","archived":false,"fork":false,"pushed_at":"2023-08-11T12:08:16.000Z","size":836,"stargazers_count":86,"open_issues_count":11,"forks_count":22,"subscribers_count":11,"default_branch":"master","last_synced_at":"2023-10-29T09:08:41.471Z","etag":null,"topics":["ble","bluetooth","bluetooth-devices","bluetooth-low-energy","bluetooth-smart","characteristics","gatt","java","manager","managment"],"latest_commit_sha":null,"homepage":"","language":"Java","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/sputnikdev.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}},"created_at":"2017-02-16T07:09:32.000Z","updated_at":"2023-09-13T10:15:20.000Z","dependencies_parsed_at":"2022-09-06T23:30:31.315Z","dependency_job_id":null,"html_url":"https://github.com/sputnikdev/bluetooth-manager","commit_stats":null,"previous_names":[],"tags_count":9,"template":null,"template_full_name":null,"purl":"pkg:github/sputnikdev/bluetooth-manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sputnikdev%2Fbluetooth-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sputnikdev%2Fbluetooth-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sputnikdev%2Fbluetooth-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sputnikdev%2Fbluetooth-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sputnikdev","download_url":"https://codeload.github.com/sputnikdev/bluetooth-manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sputnikdev%2Fbluetooth-manager/sbom","scorecard":{"id":842848,"data":{"date":"2025-08-11","repo":{"name":"github.com/sputnikdev/bluetooth-manager","commit":"7517a25387bb5a5bc75ba793d5f3756a0c41201a"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.7,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-5mg8-w23w-74h3","Warn: Project is vulnerable to: GHSA-7g45-4rm6-3mm3","Warn: Project is vulnerable to: GHSA-mvr2-9pj6-7w5j"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-23T20:51:10.080Z","repository_id":57740849,"created_at":"2025-08-23T20:51:10.080Z","updated_at":"2025-08-23T20:51:10.080Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28670366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T19:36:09.361Z","status":"ssl_error","status_checked_at":"2026-01-22T19:36:05.567Z","response_time":144,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ble","bluetooth","bluetooth-devices","bluetooth-low-energy","bluetooth-smart","characteristics","gatt","java","manager","managment"],"created_at":"2026-01-22T20:16:08.499Z","updated_at":"2026-01-22T20:16:09.299Z","avatar_url":"https://github.com/sputnikdev.png","language":"Java","readme":"[![Maven Central](https://img.shields.io/maven-central/v/org.sputnikdev/bluetooth-manager.svg)](https://mvnrepository.com/artifact/org.sputnikdev/bluetooth-manager)\n[![Build Status](https://travis-ci.org/sputnikdev/bluetooth-manager.svg?branch=master)](https://travis-ci.org/sputnikdev/bluetooth-manager)\n[![Coverage Status](https://coveralls.io/repos/github/sputnikdev/bluetooth-manager/badge.svg?branch=master)](https://coveralls.io/github/sputnikdev/bluetooth-manager?branch=master)\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/5afbd725e7b24215a350b6d9921a3684)](https://www.codacy.com/app/vkolotov/bluetooth-manager?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=sputnikdev/bluetooth-manager\u0026amp;utm_campaign=Badge_Grade)\n[![Join the chat at https://gitter.im/sputnikdev/bluetooth-manager](https://badges.gitter.im/sputnikdev/bluetooth-manager.svg)](https://gitter.im/sputnikdev/bluetooth-manager?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n# bluetooth-manager\nJava Bluetooth Manager. A library/framework for managing bluetooth adapters, bluetooth devices, GATT services and characteristics\n\nThe Bluetooth Manager is a set of java APIs which is designed to streamline all the hard work of dealing with unstable \nby its nature Bluetooth protocol. \n\n## KPIs\n\nThe following KPIs were kept in mind while designing and implementing the Bluetooth Manager:\n\n1. Flexibility in using different transports, e.g. serial port, dbus or any other (like tinyb).\n2. Extensibility in adding new supported devices, e.g. different sensors and other hardware.\n3. Robustness. Due to the nature of the Bluetooth protocol the biggest challenge is making the API stable enough \nso that end-users could use it.\n4. Comprehensive support for Bluetooth GATT specifications. This is a powerful feature which would allow users:\n    1. add any device which conforms GATT specification without developing any custom code\n    2. add custom made devices by only specifying a path to a custom defined GATT specification for a device\n \n## Implementation overview \n \nThe following diagram outlines some details of the Bluetooth Manager:\n![Bluetooth Manager diagram](bluetooth-manager.png?raw=true \"Bluetooth Manager diagram\") \n \n### Governors API\n\nThe central part of the BM architecture is \"Governors\" (examples and more info \n[BluetoothGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/BluetoothGovernor.java),  \n[AdapterGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/AdapterGovernor.java), \n[DeviceGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/DeviceGovernor.java) and \n[BluetoothManager](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/BluetoothManager.java)). \nThese are the components which define lifecycle of BT objects and contain logic for error recovery. They are similar to the transport APIs (see below), \nbut yet different because they are \"active\" components, i.e. they implement some logic for each of BT objects (adapter, device, characteristic) that make \nthe system more robust and enable the system to recover from unexpected situations such as disconnections and power outages.\n\nApart from making the system stable, the Governors are designed in a such way that they can be used externally, \nin other words it is another abstraction layer which hides some specifics/difficulties of the BT protocol behind user-friendly APIs.\n \n### Transport API\n\nA specially designed abstraction layer (transport) is used to bring support \nfor various bluetooth adapters/dongles, operation systems and hardware architecture types.\n\nThe following diagram outlines some details of the Bluetooth Manager Transport abstraction layer:\n![Transport diagram](bm-transport-abstraction-layer.png?raw=true \"Bluetooth Manager Transport abstraction layer\")\n\nThere are two implementations of the BT Transport currently:\n - [TinyB Transport](https://github.com/sputnikdev/bluetooth-manager-tinyb).\n    The TinyB transport brings support for:\n     * Conventional USB bluetooth dongles. \n     * Linux based operation systems.\n     * A wide range of hardware architectures (including some ARM based devices, e.g. Raspberry PI etc).\n - WIP: [Bluegiga Transport](https://github.com/sputnikdev/bluetooth-manager-bluegiga).\n    The Bluegiga transport brings support for:\n     * Bluegiga (BLE112) USB bluetooth dongles. \n     * Linux, Windows and OSX based operation systems.\n     * A wide range of hardware architectures (including some ARM based devices, e.g. Raspberry PI etc).\n\n#### Compatibility matrix\n\n|                                     |     TinyB     |   Bluegiga    | \n|     :---                            |     :---:     |     :---:     |\n| Windows                             |       -       |       Y       |\n| Linux                               |       Y       |       Y       |\n| Mac                                 |       -       |       Y       |\n| X86 32bit                           |       Y       |       Y       |\n| X86 64bit                           |       Y       |       Y       |\n| ARM v6 (Raspberry PI)               |       Y       |       Y       |\n| Adapters autodiscovery              |       Y       |       Y       |\n| Adapter power management            |       Y       |       -       |\n| Adapter aliases                     |       Y       |       -       |\n| BLE devices discovery               |       Y       |       Y       |\n| BR/EDR devices discovery (legacy BT)|       Y       |       -       |\n\n## Troubleshooting\n\n* [BlueGiga adapters are not getting discovered](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/6)\n* [Generic adapters (TinyB transport) are not getting discovered](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/7)\n* [Battery service does not get resolved](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/8)\n* [I've added an adapter, but I can't see any bluetooth devices](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/11)\n* Nothing happens and I have errors in the log file:\u003cbr/\u003e\n    - [GDBus.Error:org.freedesktop.DBus.Error.AccessDenied](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/9)\n    - [org.sputnikdev.bluetooth.manager.NotReadyException: Could not power adapter](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/10)\n\n## Using Bluetooth Manager\n\nStart using it by specifying maven dependencies from the Maven Central repository:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.sputnikdev\u003c/groupId\u003e\n    \u003cartifactId\u003ebluetooth-manager\u003c/artifactId\u003e\n    \u003cversion\u003eX.Y.Z\u003c/version\u003e\n\u003c/dependency\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.sputnikdev\u003c/groupId\u003e\n    \u003cartifactId\u003ebluetooth-manager-tinyb\u003c/artifactId\u003e\n    \u003cversion\u003eX.Y.Z\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThe example below shows how to set up the Bluetooth Manager and read a characteristic value.\n\n### Reading characteristic\n\n```java\nimport org.sputnikdev.bluetooth.URL;\nimport org.sputnikdev.bluetooth.manager.CharacteristicGovernor;\nimport org.sputnikdev.bluetooth.manager.impl.BluetoothManagerBuilder;\n\npublic final class BluetoothManagerSimpleTest {\n\n    public static void main(String[] args) throws Exception {\n        new BluetoothManagerBuilder()\n                .withTinyBTransport(true)\n                .withBlueGigaTransport(\"^*.$\")\n                .build()\n                .getCharacteristicGovernor(new URL(\"/XX:XX:XX:XX:XX:XX/F7:EC:62:B9:CF:1F/\" \n                        + \"0000180f-0000-1000-8000-00805f9b34fb/00002a19-0000-1000-8000-00805f9b34fb\"), true)\n                .whenReady(CharacteristicGovernor::read)\n                .thenAccept(data -\u003e {\n                    System.out.println(\"Battery level: \" + data[0]);   \n                }).get();\n    }\n    \n}\n```\nHere is what happening behind the scene in the example above:\n* detecting what adapters are installed in the system (Generic and BlueGiga)\n* automatically loading native libraries for the current architecture type (CPU type and OS type)\n* setting up bluetooth manager\n* choosing the nearest bluetooth adapter\n* connecting to the bluetooth device\n* resolving GATT services and characteristics\n* reading the \"Battery Level\" characteristic\n\n### Receiving characteristic notifications\n\n```java\nimport org.sputnikdev.bluetooth.URL;\nimport org.sputnikdev.bluetooth.manager.BluetoothManager;\nimport org.sputnikdev.bluetooth.manager.impl.BluetoothManagerBuilder;\n\npublic class BluetoothManagerSimpleTest {\n\n    public static void main(String args[]) {\n        // get the Bluetooth Manager\n        BluetoothManager manager = new BluetoothManagerBuilder()\n                .withTinyBTransport(true)\n                .withBlueGigaTransport(\"^*.$\")\n                .build();\n        // define a URL pointing to the target characteristic\n        URL url = new URL(\"/88:6B:0F:01:90:CA/CF:FC:9E:B2:0E:63/\" +\n                \"0000180f-0000-1000-8000-00805f9b34fb/00002a19-0000-1000-8000-00805f9b34fb\");\n        // subscribe to the characteristic notification\n        manager.getCharacteristicGovernor(url, true).addValueListener(value -\u003e {\n            System.out.println(\"Battery level: \" + value[0]);\n        });\n        // do your other stuff\n        Thread.sleep(10000);\n    }\n}\n```\n\nMore examples here: [bluetooth-cli](https://github.com/sputnikdev/bluetooth-cli/tree/master/src/main/java/org/sputnikdev/bluetooth/examples)\n\n---\n## Contribution\n\nYou are welcome to contribute to the project, the project environment is designed to make it easy by using:\n* Travis CI to release artifacts directly to the Maven Central repository.\n* Code style rules to support clarity and supportability. The results can be seen in the Codacy. \n* Code coverage reports in the Coveralls to maintain sustainability. 100% of code coverage with unittests is the target.\n\nThe build process is streamlined by using standard maven tools. \n\nTo build the project with maven:\n```bash\nmvn clean install\n```\n\nTo cut a new release and upload it to the Maven Central Repository:\n```bash\nmvn release:prepare -B\nmvn release:perform\n```\nTravis CI process will take care of everything, you will find a new artifact in the Maven Central repository when the release process finishes successfully.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsputnikdev%2Fbluetooth-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsputnikdev%2Fbluetooth-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsputnikdev%2Fbluetooth-manager/lists"}