hypfvieh/bluez-dbus

bluetooth library for linux OSes using DBus and bluez (http://www.bluez.org/).

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.hypfvieh:bluez-dbus:0.1.1'
	}

	dependencies {
		implementation("com.github.hypfvieh:bluez-dbus:0.1.1")
	}

	<dependency>
	    <groupId>com.github.hypfvieh</groupId>
	    <artifactId>bluez-dbus</artifactId>
	    <version>0.1.1</version>
	</dependency>


                            
    libraryDependencies += "com.github.hypfvieh" % "bluez-dbus" % "0.1.1"


                            
    :dependencies [[com.github.hypfvieh/bluez-dbus "0.1.1"]]

Readme

bluez-dbus

bluetooth library for linux OSes using DBus and bluez.

This project was inspired by tinyb, but does not require any wrapper library as it is based on a newer version of dbus-java which uses jnr-unixsocket.

This library has been tested with Ubuntu 22.04 (AMD64) and bluez library 5.64.

Compatibility

The different versions of bluez-dbus are using different versions of dbus-java which requires modern Java versions. Here is a list of which bluez-dbus versions uses which dbus-java and the required Java version to use.

| bluez-java Version | dbus-java Version | minimum Java Version | | ------------------ | ----------------- | -------------------- | | 0.0.x | 2.7.x | Java 1.7 | | 0.1.x | 3.x | Java 1.8 | | 0.2.x | 4.3.x | Java 11 | | 0.3.x | 5.x | Java 17 |

Usage

When using the library directly, you have to add at least one dbus-java transport to your project as well. There are different transports available. For usage with DBus you usually need a UnixSocket providing transport.

| Transport | Usage | | ------------------------------------- | ------------------------------------------------------------------------------------------ | | dbus-java-transport-jnr-unixsocket | Use this if you need filedescriptor support as well (see below) | | dbus-java-transport-junixsocket | Alternative if you don't want to use jnr (beta support in dbus-java 4.x), supports<br>filedescriptor without additional libraries. | | dbus-java-transport-native-unixsocket | Use Java native implementation for UnixSockets. Needs at least Java 16, does not support<br>filedescriptor at all. | | dbus-java-transport-tcp | TCP implementation, only needed when your DBusDaemon is configured to use TCP as well<br>as/instead of UnixSockets. |

If you use the OSGi bundle, you don't have to add anything. The OSGi bundle will use jnr-unixsocket transport as default in bluez-dbus version 0.2.x. It will be changed to junixsocket-transport in bluez-dbus 0.3.x.

filedescriptor support

If you want to use filedescriptor passing in any bluez method, you have to add Robert Middleton's dbus-java-nativefd library to your project if you are using jnr-unixsocket-transport. The library can be found here:

<dependency>
    <groupId>com.rm5248</groupId>
    <artifactId>dbus-java-nativefd</artifactId>
    <version>2.0</version>
</dependency>

If you use the native-transport, you cannot use filedescriptor's because Java native implementation of UnixSockets only has a limited functionality. For most cases this implementation should be fine. In some special cases like filedescriptors it isn't good enough.

Starting from bluez-java 0.3.x, dbus-java 5.x is used which has proper support for junixsocket. JUnixsocket is another implementation for UnixSockets like jnr-unixsockets but with a richer feature set out of the box. It supports filedescriptors without the need of additional libraries.

To build a newer bluez-library for Ubuntu (16.04 has an older version than 5.50):

Download new bluez library from http://www.bluez.org/download/
Install Ubuntu build essentials:
sudo apt-get install build-essential
Install required additional dependencies:
sudo apt-get install libdbus-1-dev libudev-dev libical-dev libreadline-dev checkinstall libglib2.0-dev
Extract the downloaded bluez-tarball:
tar xfvJ bluez-5.50.tar.xz
Run ./configure in the extracted bluez tarball:
./configure --prefix=/usr --libexecdir=/usr/lib --enable-manpages
run checkinstall in bluez tarball directory: sudo checkinstall
Answer 'y' to question if default docs should be created
Enter a description (e.g. New bluez library), press enter and then CTRL+D
In checkinstall:
Go to Menu option 13 (Replaces)
Enter: bluez-obexd, bluez-cups, bluez-hcidump, bluez-btsco, bluez-tools
Press Enter to start the build
Install the generated .deb files:
sudo dpkg -i bluez_5.50-1_amd64.deb

Changelog:

Version 0.3.3 (not released yet):

nothing so far

Version 0.3.2 (2025-04-20):

Improved scanning/refreshing behavior of DeviceManager #PR67, thanks to joerg1985
Added new method setLazyScan to enable/disable re-querying of GATT services from already known devices when scanning

Version 0.3.1 (2025-01-20):

Fixed issues with OSGi Bundle, #64, #PR65, thanks to joerg1985

Version 0.3.0 (2024-08-02):

Requires Java 17
Uses dbus-java 5.x

Version 0.2.0 (2023-07-21):

Requires Java 11
Uses dbus-java 4.x
Updated interfaces to comply with bluez 5.64
Issue #48 allow unregistering of signal handlers
Issue #51 added mesh interface classes

Version 0.1.3:

Various bugfixes: #35, #36, #38
Updated dependency versions

Version 0.1.2:

Multi module maven project
Provide a new artifact for usage with OSGi (bluez-java-osgi)
Changed visibility of some methods to public
Smaller bugfixes
Updated interface classes to match with bluez 5.54 - Please note: mesh classes are still missing, PRs welcome