https://github.com/sputnikdev/bluetooth-manager
Java Bluetooth Manager. A library/framework for managing bluetooth adapters, bluetooth devices, GATT services and characteristics
https://github.com/sputnikdev/bluetooth-manager
ble bluetooth bluetooth-devices bluetooth-low-energy bluetooth-smart characteristics gatt java manager managment
Last synced: 2 days ago
JSON representation
Java Bluetooth Manager. A library/framework for managing bluetooth adapters, bluetooth devices, GATT services and characteristics
- Host: GitHub
- URL: https://github.com/sputnikdev/bluetooth-manager
- Owner: sputnikdev
- License: apache-2.0
- Created: 2017-02-16T07:09:32.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2023-08-11T12:08:16.000Z (over 2 years ago)
- Last Synced: 2023-10-29T09:08:41.471Z (about 2 years ago)
- Topics: ble, bluetooth, bluetooth-devices, bluetooth-low-energy, bluetooth-smart, characteristics, gatt, java, manager, managment
- Language: Java
- Homepage:
- Size: 816 KB
- Stars: 86
- Watchers: 11
- Forks: 22
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://mvnrepository.com/artifact/org.sputnikdev/bluetooth-manager)
[](https://travis-ci.org/sputnikdev/bluetooth-manager)
[](https://coveralls.io/github/sputnikdev/bluetooth-manager?branch=master)
[](https://www.codacy.com/app/vkolotov/bluetooth-manager?utm_source=github.com&utm_medium=referral&utm_content=sputnikdev/bluetooth-manager&utm_campaign=Badge_Grade)
[](https://gitter.im/sputnikdev/bluetooth-manager?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
# bluetooth-manager
Java Bluetooth Manager. A library/framework for managing bluetooth adapters, bluetooth devices, GATT services and characteristics
The Bluetooth Manager is a set of java APIs which is designed to streamline all the hard work of dealing with unstable
by its nature Bluetooth protocol.
## KPIs
The following KPIs were kept in mind while designing and implementing the Bluetooth Manager:
1. Flexibility in using different transports, e.g. serial port, dbus or any other (like tinyb).
2. Extensibility in adding new supported devices, e.g. different sensors and other hardware.
3. Robustness. Due to the nature of the Bluetooth protocol the biggest challenge is making the API stable enough
so that end-users could use it.
4. Comprehensive support for Bluetooth GATT specifications. This is a powerful feature which would allow users:
1. add any device which conforms GATT specification without developing any custom code
2. add custom made devices by only specifying a path to a custom defined GATT specification for a device
## Implementation overview
The following diagram outlines some details of the Bluetooth Manager:
### Governors API
The central part of the BM architecture is "Governors" (examples and more info
[BluetoothGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/BluetoothGovernor.java),
[AdapterGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/AdapterGovernor.java),
[DeviceGovernor](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/DeviceGovernor.java) and
[BluetoothManager](https://github.com/sputnikdev/bluetooth-manager/blob/master/src/main/java/org/sputnikdev/bluetooth/manager/BluetoothManager.java)).
These are the components which define lifecycle of BT objects and contain logic for error recovery. They are similar to the transport APIs (see below),
but yet different because they are "active" components, i.e. they implement some logic for each of BT objects (adapter, device, characteristic) that make
the system more robust and enable the system to recover from unexpected situations such as disconnections and power outages.
Apart from making the system stable, the Governors are designed in a such way that they can be used externally,
in other words it is another abstraction layer which hides some specifics/difficulties of the BT protocol behind user-friendly APIs.
### Transport API
A specially designed abstraction layer (transport) is used to bring support
for various bluetooth adapters/dongles, operation systems and hardware architecture types.
The following diagram outlines some details of the Bluetooth Manager Transport abstraction layer:
There are two implementations of the BT Transport currently:
- [TinyB Transport](https://github.com/sputnikdev/bluetooth-manager-tinyb).
The TinyB transport brings support for:
* Conventional USB bluetooth dongles.
* Linux based operation systems.
* A wide range of hardware architectures (including some ARM based devices, e.g. Raspberry PI etc).
- WIP: [Bluegiga Transport](https://github.com/sputnikdev/bluetooth-manager-bluegiga).
The Bluegiga transport brings support for:
* Bluegiga (BLE112) USB bluetooth dongles.
* Linux, Windows and OSX based operation systems.
* A wide range of hardware architectures (including some ARM based devices, e.g. Raspberry PI etc).
#### Compatibility matrix
| | TinyB | Bluegiga |
| :--- | :---: | :---: |
| Windows | - | Y |
| Linux | Y | Y |
| Mac | - | Y |
| X86 32bit | Y | Y |
| X86 64bit | Y | Y |
| ARM v6 (Raspberry PI) | Y | Y |
| Adapters autodiscovery | Y | Y |
| Adapter power management | Y | - |
| Adapter aliases | Y | - |
| BLE devices discovery | Y | Y |
| BR/EDR devices discovery (legacy BT)| Y | - |
## Troubleshooting
* [BlueGiga adapters are not getting discovered](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/6)
* [Generic adapters (TinyB transport) are not getting discovered](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/7)
* [Battery service does not get resolved](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/8)
* [I've added an adapter, but I can't see any bluetooth devices](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/11)
* Nothing happens and I have errors in the log file:
- [GDBus.Error:org.freedesktop.DBus.Error.AccessDenied](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/9)
- [org.sputnikdev.bluetooth.manager.NotReadyException: Could not power adapter](https://github.com/sputnikdev/eclipse-smarthome-bluetooth-binding/issues/10)
## Using Bluetooth Manager
Start using it by specifying maven dependencies from the Maven Central repository:
```xml
org.sputnikdev
bluetooth-manager
X.Y.Z
org.sputnikdev
bluetooth-manager-tinyb
X.Y.Z
```
The example below shows how to set up the Bluetooth Manager and read a characteristic value.
### Reading characteristic
```java
import org.sputnikdev.bluetooth.URL;
import org.sputnikdev.bluetooth.manager.CharacteristicGovernor;
import org.sputnikdev.bluetooth.manager.impl.BluetoothManagerBuilder;
public final class BluetoothManagerSimpleTest {
public static void main(String[] args) throws Exception {
new BluetoothManagerBuilder()
.withTinyBTransport(true)
.withBlueGigaTransport("^*.$")
.build()
.getCharacteristicGovernor(new URL("/XX:XX:XX:XX:XX:XX/F7:EC:62:B9:CF:1F/"
+ "0000180f-0000-1000-8000-00805f9b34fb/00002a19-0000-1000-8000-00805f9b34fb"), true)
.whenReady(CharacteristicGovernor::read)
.thenAccept(data -> {
System.out.println("Battery level: " + data[0]);
}).get();
}
}
```
Here is what happening behind the scene in the example above:
* detecting what adapters are installed in the system (Generic and BlueGiga)
* automatically loading native libraries for the current architecture type (CPU type and OS type)
* setting up bluetooth manager
* choosing the nearest bluetooth adapter
* connecting to the bluetooth device
* resolving GATT services and characteristics
* reading the "Battery Level" characteristic
### Receiving characteristic notifications
```java
import org.sputnikdev.bluetooth.URL;
import org.sputnikdev.bluetooth.manager.BluetoothManager;
import org.sputnikdev.bluetooth.manager.impl.BluetoothManagerBuilder;
public class BluetoothManagerSimpleTest {
public static void main(String args[]) {
// get the Bluetooth Manager
BluetoothManager manager = new BluetoothManagerBuilder()
.withTinyBTransport(true)
.withBlueGigaTransport("^*.$")
.build();
// define a URL pointing to the target characteristic
URL url = new URL("/88:6B:0F:01:90:CA/CF:FC:9E:B2:0E:63/" +
"0000180f-0000-1000-8000-00805f9b34fb/00002a19-0000-1000-8000-00805f9b34fb");
// subscribe to the characteristic notification
manager.getCharacteristicGovernor(url, true).addValueListener(value -> {
System.out.println("Battery level: " + value[0]);
});
// do your other stuff
Thread.sleep(10000);
}
}
```
More examples here: [bluetooth-cli](https://github.com/sputnikdev/bluetooth-cli/tree/master/src/main/java/org/sputnikdev/bluetooth/examples)
---
## Contribution
You are welcome to contribute to the project, the project environment is designed to make it easy by using:
* Travis CI to release artifacts directly to the Maven Central repository.
* Code style rules to support clarity and supportability. The results can be seen in the Codacy.
* Code coverage reports in the Coveralls to maintain sustainability. 100% of code coverage with unittests is the target.
The build process is streamlined by using standard maven tools.
To build the project with maven:
```bash
mvn clean install
```
To cut a new release and upload it to the Maven Central Repository:
```bash
mvn release:prepare -B
mvn release:perform
```
Travis CI process will take care of everything, you will find a new artifact in the Maven Central repository when the release process finishes successfully.