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.
The following KPIs were kept in mind while designing and implementing the Bluetooth Manager:
- Flexibility in using different transports, e.g. serial port, dbus or any other (like tinyb).
- Extensibility in adding new supported devices, e.g. different sensors and other hardware.
- 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.
- Comprehensive support for Bluetooth GATT specifications. This is a powerful feature which would allow users:
- add any device which conforms GATT specification without developing any custom code
- add custom made devices by only specifying a path to a custom defined GATT specification for a device
The following diagram outlines some details of the Bluetooth Manager:
The central part of the BM architecture is "Governors" (examples and more info
BluetoothGovernor,
AdapterGovernor,
DeviceGovernor and
BluetoothManager).
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.
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.
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.
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).
| 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 | - |
- BlueGiga adapters are not getting discovered
- Generic adapters (TinyB transport) are not getting discovered
- Battery service does not get resolved
- I've added an adapter, but I can't see any bluetooth devices
- Nothing happens and I have errors in the log file:
Start using it by specifying maven dependencies from the Maven Central repository:
<dependency>
<groupId>org.sputnikdev</groupId>
<artifactId>bluetooth-manager</artifactId>
<version>X.Y.Z</version>
</dependency>
<dependency>
<groupId>org.sputnikdev</groupId>
<artifactId>bluetooth-manager-tinyb</artifactId>
<version>X.Y.Z</version>
</dependency>The example below shows how to set up the Bluetooth Manager and read a characteristic value.
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
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
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:
mvn clean installTo cut a new release and upload it to the Maven Central Repository:
mvn release:prepare -B
mvn release:performTravis CI process will take care of everything, you will find a new artifact in the Maven Central repository when the release process finishes successfully.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent