v1.0.0

bt-proxy is an ESPHome-compatible Bluetooth Proxy for Raspberry Pi (and any Linux host with BlueZ). It speaks the ESPHome Native API, so Home Assistant discovers and uses it just like an ESP32-based Bluetooth proxy.

Compatible with the latest Home Assistant

Recent Home Assistant versions request passive BLE scanning by default. bt-proxy now handles this cleanly:

• Passive scanning is used when the stack supports it — BlueZ ≥ 5.56 with bluetoothd --experimental (passing the or_patterns BlueZ requires).
• When passive isn't available — older BlueZ, or bluetoothd not started with --experimental — it automatically falls back to active scanning instead of failing. The fallback is decided once per run, and the effective mode is reported back to Home Assistant.
• Reports a current ESPHome version, clearing Home Assistant's "update your Bluetooth proxy" warning.

Also in this release

• Resilient scanner start: transient BlueZ errors (e.g. InProgress) are retried with backoff instead of crashing the process. On persistent failure the proxy stays up and self-heals in the background, logging a hint to HCI-reset a wedged adapter.

Features

• BLE scanning (passive/active) with raw advertisement forwarding
• Active GATT connections: service discovery, read/write characteristics & descriptors, notifications
• mDNS discovery; wire-compatible with aioesphomeapi and the Home Assistant ESPHome integration

Run it

docker run -d \
  --name bt-proxy \
  --restart unless-stopped \
  --net=host \
  --privileged \
  -v /var/run/dbus:/var/run/dbus \
  ghcr.io/denvera/bt-proxy

--net=host is required for mDNS discovery; --privileged grants Bluetooth adapter access (or use --cap-add=NET_ADMIN --cap-add=NET_RAW); the D-Bus mount lets it talk to BlueZ. See the README for uv / systemd usage and all CLI options.