Installing bluetooth binding

Setup, Configuration and Use Migration
1

I tried to add this binding but get errors. On the ubuntu docker side seems everything to work. I modified the file docker-compose-openhab.yml to

services:
  openhab:
    image: "openhab/openhab:5.1.3"
    restart: always
    network_mode: host

    privileged: true
    cap_add:
      - NET_ADMIN
      - SYS_ADMIN

    volumes:
      - "/etc/localtime:/etc/localtime:ro"
      - "/etc/timezone:/etc/timezone:ro"
      - "/home/mynuc/docker/openhab5.1.3/addons:/openhab/addons"
      - "/home/mynuc/docker/openhab5.1.3/conf:/openhab/conf"
      - "/home/mynuc/docker/openhab5.1.3/userdata:/openhab/userdata"
      - "/home/mynuc/docker/speedtest/speedtest:/usr/bin/speedtest"

      - "/var/run/dbus:/var/run/dbus"
      - "/etc/machine-id:/etc/machine-id:ro"

    environment:
      CRYPTO_POLICY: "unlimited"
      EXTRA_JAVA_OPTS: "-Duser.timezone=Europe/Amsterdam"
      OPENHAB_HTTP_PORT: "8080"
      OPENHAB_HTTPS_PORT: "8443"

and hciconfig gives me

hci0:   Type: Primary  Bus: USB
        BD Address: BC:FC:E7:29:09:73  ACL MTU: 1021:6  SCO MTU: 255:12
        UP RUNNING
        RX bytes:1682 acl:0 sco:0 events:186 errors:0
        TX bytes:34411 acl:0 sco:0 commands:186 errors:0

But in the logfile I get

2026-03-07 16:46:39.506 [WARN ] [mmon.WrappedScheduledExecutorService] - Scheduled runnable ended with an exception: 
java.util.concurrent.CompletionException: java.lang.NullPointerException: Cannot invoke "org.freedesktop.dbus.connections.transports.AbstractTransport.getTransportConfig()" because the return value of "org.freedesktop.dbus.connections.base.AbstractConnectionBase.getTransport()" is null
	at java.util.concurrent.CompletableFuture.encodeThrowable(CompletableFuture.java:332) ~[?:?]
	at java.util.concurrent.CompletableFuture.completeThrowable(CompletableFuture.java:347) ~[?:?]
	at java.util.concurrent.CompletableFuture$UniCompose.tryFire(CompletableFuture.java:1141) ~[?:?]
	at java.util.concurrent.CompletableFuture.postComplete(CompletableFuture.java:510) ~[?:?]
	at java.util.concurrent.CompletableFuture.completeExceptionally(CompletableFuture.java:2194) ~[?:?]
	at org.openhab.binding.bluetooth.util.RetryFuture$CallableTask.run(RetryFuture.java:76) ~[?:?]
	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:572) ~[?:?]
	at java.util.concurrent.FutureTask.run(FutureTask.java:317) ~[?:?]
	at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:304) ~[?:?]
	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1144) ~[?:?]
	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:642) ~[?:?]
	at java.lang.Thread.run(Thread.java:1583) [?:?]
Caused by: java.lang.NullPointerException: Cannot invoke "org.freedesktop.dbus.connections.transports.AbstractTransport.getTransportConfig()" because the return value of "org.freedesktop.dbus.connections.base.AbstractConnectionBase.getTransport()" is null
	at org.freedesktop.dbus.connections.base.AbstractConnectionBase.getTransportConfig(AbstractConnectionBase.java:510) ~[?:?]
	at org.freedesktop.dbus.connections.impl.DBusConnection.connectImpl(DBusConnection.java:101) ~[?:?]
	at org.freedesktop.dbus.connections.impl.DBusConnectionBuilder.build(DBusConnectionBuilder.java:184) ~[?:?]
	at com.github.hypfvieh.bluetooth.DeviceManager.createInstance(DeviceManager.java:67) ~[?:?]
	at org.openhab.binding.bluetooth.bluez.internal.DeviceManagerFactory.lambda$0(DeviceManagerFactory.java:83) ~[?:?]
	at org.openhab.binding.bluetooth.util.RetryFuture$CallableTask.run(RetryFuture.java:67) ~[?:?]
	... 6 more

What is missing?

2

On the host or in the container?

Which adapter are you using with the BT binding? They all have different requirements but one big one is you can’t be running anything on the host that uses BT. For example, if you want to use bluez, you cannot have bluez running on the host. Only one service can access the hardware at a time.

Overall, getting bluetooth working inside the OH container is such a pain I can’t recommend it. Even if you get it to work it’s going to be brittle and annoying. If the devices you are looking to use are supported by other services like Theengs Gateway or Wave2MQTT or sensorReporter, etc. you will find it all much easier to set up initially and maintain in the long run.

3

Thanks. I don’t want to use it al all but the problem is that the latest version of ESPHome requires it. I hope they will change the requirements

4

I guess you do not have a Bluetooth dongle you want to use, but just to get the ESPHome binding running?

I’m using both docker and bare-metal, do not have a BT dongle but use the BLuetooth proxying via ESPHome. I do not see these error messages, so if you configure such a BLE proxy maybe OH stops insisting that the binding should communicate with BlueZ.

Bridge bluetooth:esphome:proxy "ESPHome BLE Advertisement listener" [backgroundDiscovery = false] {
}
5

The Bluetooth binding always complains on my setup as well: [bluetooth.bluez] - "Critical error while reading DBUS response" · Issue #19907 · openhab/openhab-addons · GitHub

Maybe there’s some relevance?

6

Yes I bought a BT dongle. If not connected you don’t get valid feedback on hciconfig.

7

I found some info about the docker. Maybe someone can confirm this. The errors

org.freedesktop.dbus.exceptions.FatalDBusException: 
java.io.EOFException: (1) Underlying transport returned -1

This seems to be the limitation of docker-snap. Can this be the case? And who moved to Docker (Apt) or is using this?

8

Are you using de BT from a ESP32 device?

9

Yes, but only in conjunction with the BTHome binding (means only eavesdropping on traffic, no connection attempt to the BT device since ESPHome binding doesn’t support it yet).

10

In the GUI I can find the BTHome binding but I work with addons.cfg so can you point me to the jar file. Assuming this is different from the ESPHome binding. Not sure if I should be able to find it with this info marketplace:156830

11

I don’t know if OH supports adding marketplace bindings to the addons.cfg file. If not you can either install it manually from BTHome Binding [4.0.0.0;6.0.0.0) - or add this jar file to your addons folder (bonus: it won’t be automatically removed when you upgrade OH); https://github.com/seime/openhab-bthome/releases/download/latest_oh4/no.seime.openhab.binding.bluetooth.bthome-4.1.0-SNAPSHOT.jar