BlueZ D-Bus binding: reliable state detection and Docker compatibility

[poodle64]

Summary

Noble's HCI binding has persistent issues with stateChange not firing reliably on Linux (see #66). The root cause is that the HCI user-channel binding requires exclusive adapter access, which conflicts with BlueZ. In Docker containers, the problem is compounded: /dev/hciX devices may not exist, hci-ble fails silently, and there is no fallback.

We have built a BlueZ D-Bus binding for Noble that resolves these issues by using BlueZ's native D-Bus API (org.bluez) instead of raw HCI.

Problems with the HCI binding on Linux

1. stateChange not triggered ('stateChange' is not reliably triggered on Raspberry Pi 4 #66): The HCI binding opens a user-channel socket which requires exclusive adapter access. If BlueZ is managing the adapter (which it is by default on every systemd-based distro), the socket open either fails silently or BlueZ and Noble fight over the adapter state.

2. Docker incompatibility: In containers, /dev/hciX often doesn't exist even with --privileged or device passthrough. The HCI binding's Hci.init() fails before emitting any state, leaving consumers waiting forever for poweredOn.

3. No graceful degradation: When HCI binding initialisation fails, Noble doesn't fall back to an alternative. The consumer gets no stateChange event and no error — it just hangs.

Our solution: BlueZ D-Bus binding

We implemented a D-Bus binding (lib/bluez-dbus/) that talks to BlueZ via org.bluez over the system D-Bus socket. This:

• Uses BlueZ natively: No exclusive adapter access needed. Works alongside BlueZ, bluetoothctl, and other D-Bus clients.
• Works in Docker: Only needs the D-Bus system socket mounted (/run/dbus/system_bus_socket). No /dev/hciX device nodes required.
• Reliable state detection: Reads adapter Powered property via D-Bus org.bluez.Adapter1. State changes are delivered via D-Bus PropertiesChanged signals — no polling, no race conditions.
• Full scanning and connection support: Uses org.bluez.Adapter1.StartDiscovery / StopDiscovery for scanning, org.bluez.Device1.Connect / Disconnect for connections, and org.bluez.GattService1 / GattCharacteristic1 for GATT operations.

Architecture

Noble API
  └── BlueZ D-Bus Binding
        ├── adapter.js      — Adapter lifecycle (power, state, reset)
        ├── scanner.js      — BLE discovery via StartDiscovery/StopDiscovery
        ├── connection.js   — Device connection management
        ├── gatt.js         — GATT service/characteristic discovery and I/O
        └── utils.js        — UUID/path conversion helpers
              │
              └── node-dbus-next (D-Bus protocol library)
                    │
                    └── /run/dbus/system_bus_socket
                          │
                          └── BlueZ (org.bluez)

Key commits

Our fork: poodle64/noble

• d9de461 feat: add dbus-next dependency for BlueZ D-Bus binding
• 6427cf4 feat(bluez-dbus): add utils module
• 03e9c6a feat(bluez-dbus): add adapter lifecycle module
• bb715e4 feat(bluez-dbus): add scanner module
• 1ba8e8b feat(bluez-dbus): add device connection manager
• 4be24ff feat(bluez-dbus): add GATT manager
• abfec53 feat(bluez-dbus): add main binding module
• bab31d4 feat(bluez-dbus): add binding selection to resolve-bindings

Binding selection

The D-Bus binding is selected automatically when resolve-bindings detects Linux and an available D-Bus socket. The HCI binding remains available as a fallback for systems without BlueZ (embedded, custom kernels).

Testing

Tested extensively with Matter device commissioning (Nanoleaf NL75) in Docker on NixOS. BlueZ 5.79, kernel 6.12. Scanning, connecting, GATT discovery, and characteristic read/write all work reliably.

Happy to contribute this upstream if there's interest — the binding is fairly self-contained in lib/bluez-dbus/.

[stoprocent]

Sure, that would be amazing. I didn't like the D bus because it was missing some of the core features that I needed. But if we keep both, then I think it's great. I use HCI extensively. I have a custom UART BLE dongle.

[poodle64]

That's exactly how we've built it. The HCI binding is completely untouched; the D-Bus binding is an additional option that sits alongside it. The selection logic in resolve-bindings.js auto-detects: if a D-Bus socket is available and BlueZ is running, it uses the D-Bus binding. Otherwise it falls back to HCI. There's also a NOBLE_BINDING env var override if someone wants to force one or the other.

In practice we actually ended up needing both in the same process. Our D-Bus binding handles state detection (which is what breaks in Docker), but for some devices (Nanoleaf NL75) we discovered that BlueZ's Device1.Connect() fails while raw HCI connects fine. So the scanner has a GATT probe that temporarily spins up an HCI binding instance to connect and check for services, then hands back to D-Bus for everything else.

Your UART dongle use case would stay on HCI as before. Nothing changes for existing users unless they have a D-Bus socket present.

Happy to clean up the code and put together a PR if you're interested. The binding is working in production for us (Matter BLE commissioning via matterjs-server in Docker).

[stoprocent]

Hey, are you creating merge requests for this?

[ohmantics]

@poodle64 Your fork isn't public.

I think I'm hitting similar problems on Linux, manifesting as disconnects not closing the L2CAP connection and leaving things stuck connected.

[github-actions]

This issue is stale because it has been open for 30 days with no activity.

[stoprocent]

Hey @poodle64 any plans to publish ?

[stoprocent]

Ok I did add experimental DBUS support, tbh wasnt that hard especially with claudes help: #79

Im just testing scanning connecting and everything seems to work smooth.