Bluetooth Proxy

Home Assistant can expand its Bluetooth reach by communicating through the Bluetooth proxy component in ESPHome. The individual device integrations in Home Assistant (such as BTHome) will receive the data from the Bluetooth Integration in Home Assistant which automatically aggregates all ESPHome Bluetooth proxies with any USB Bluetooth Adapters you might have. This exceptional feature offers fault tolerant connection between the Bluetooth devices and Home Assistant.

Note that while this component is named bluetooth_proxy, only BLE devices (and their Home Assistant integrations) are supported.

If you'd like to buy a ready-made Bluetooth proxy or flash your own device, see ESPHome projects with Bluetooth proxy support.

Scan source and platform support

The Bluetooth proxy does not scan on its own. It attaches to a BLE tracker hub — the BLE scanner for your chip — which supplies the advertisements, and forwards them to Home Assistant. Add the tracker for your platform to the configuration alongside bluetooth_proxy:

Platform	BLE tracker hub	Raw advertisements	Active connections
ESP32	ESP32 BLE Tracker	✅	✅
BK72xx (LibreTiny)*	`bk72xx_ble_tracker`	✅	—
LN882H (LibreTiny)	`ln882h_ble_tracker`	✅	—

* BK72xx requires a BLE 5.x Beken SDK, so only the BLE-5.x BK72xx chips are supported. See the bk72xx_ble_tracker docs for the supported-chip list.

Raw advertisement proxying — forwarding the advertisements that BLE devices broadcast (BTHome, ATC, iBeacon and similar) — works on every platform. Active connections, which let Home Assistant read from and write to a device over a live GATT connection, are ESP32-only; on LibreTiny hubs the Bluetooth proxy is an advertisement proxy.

# ESP32
esp32_ble_tracker:
bluetooth_proxy:

# BK72xx — BLE 5.x (LibreTiny)
bk72xx_ble_tracker:
bluetooth_proxy:

# LN882H (LibreTiny)
ln882h_ble_tracker:
bluetooth_proxy:

In every case the proxy attaches to the BLE tracker declared alongside it. You can also write bluetooth_proxy: on its own — the matching tracker for your chip (esp32_ble_tracker, bk72xx_ble_tracker or ln882h_ble_tracker) is added automatically.

Configuration

bluetooth_proxy:
  # Active connections are now enabled by default
  # To disable active connections (previous default behavior), use:
  # active: false

The options below configure active connections and apply to ESP32 only. On LibreTiny hubs the proxy accepts only id and ble_id (the BLE tracker to attach to — auto-resolved when a single tracker is configured).

active (Optional, boolean): Enables proxying active GATT connections to BLE devices. This is separate from active scanning (configured on the BLE tracker). Defaults to true. ESP32-only.
cache_services (Optional, boolean): Enables caching GATT services in NVS flash storage which significantly speeds up active connections. Defaults to true. ESP32-only.
connection_slots (Optional, int): The maximum number of BLE connection slots to use. Each configured slot consumes ~1KB of RAM, with a maximum of 9. It is recommended not to exceed 5 connection slots to avoid stability and memory issues. Defaults to 3. Ethernet-based proxies can generally handle 4 connection slots reliably. The value must not exceed the total configured max_connections for ESP32 BLE. ESP32-only.

The Bluetooth proxy depends on the BLE tracker for your platform — ESP32 BLE Tracker on ESP32, or bk72xx_ble_tracker / ln882h_ble_tracker on LibreTiny — so make sure to add it to your configuration.

How active connections work (ESP32 only)

The Bluetooth proxy provides Home Assistant with a limited number of simultaneous active GATT connections (configured via connection_slots). The default is 3 slots. Ethernet-based proxies can generally handle 4 slots reliably since they don't share the radio with WiFi traffic. Set connection_slots: 4 if you need more connections (each slot uses additional RAM).

Devices that stay connected continuously (like some locks or thermostats) use one slot the entire time. Devices that connect briefly to exchange data and then disconnect (like many sensors) free up the slot for other devices, so you can use more devices than you have slots.

Passively broadcasted sensor data (advertised by devices without requiring active connections, such as many BTHome sensors) is received separately and is not limited by the number of connection slots — and is the only mode used by LibreTiny hubs.

Improving reception performance

NOTE

The default scan parameters are recommended for most users. Changing interval or window from their defaults typically provides no meaningful benefit while increasing CPU usage and network traffic. Aggressive scan settings can cause overheating on PoE-based proxies and WiFi instability on WiFi-based proxies.

On ESP32, use a board with an Ethernet connection to the network to offload the radio module from WiFi traffic, which improves Bluetooth performance. For best results, use a board with an external antenna (e.g., Olimex ESP32-PoE-ISO-EA over Olimex ESP32-PoE-ISO).

On LibreTiny, the BK72xx (BLE 5.x) and LN882H are single-core, WiFi-only modules — WiFi and BLE share one CPU core, so continuous scanning can interfere with the initial connection to Home Assistant. Start scanning only once Home Assistant connects; see the single-core guidance on the bk72xx_ble_tracker / ln882h_ble_tracker pages (and the LibreTiny sample below).

Passive vs active scanning

Passive scanning works for most BLE devices and is sufficient for ongoing operation. Active scanning requests additional scan response data from devices and is typically only needed when initially adding new devices to Home Assistant. Active scanning also increases battery drain on battery-powered BLE devices.

Passive vs active scanning is configured on the BLE tracker, not on the proxy. The ESP32 BLE Tracker defaults to active scanning (active: true); if you experience overheating you can switch to passive scanning when your devices don't require active scans:

esp32_ble_tracker:
  scan_parameters:
    active: false

On LibreTiny, set active: on ln882h_ble_tracker the same way; the BK72xx chips scan passively only.

Avoid placing the node in racks, close to routers/switches or other network equipment as EMI interference will degrade Bluetooth signal reception. For best results put as far away as possible, at least 3 meters distance from any other such equipment. Place your ESPHome devices close to the Bluetooth devices that you want to interact with for the best experience.

Complete sample configurations

ESP32 — Wi-Fi

A complete sample recommended configuration for a Wi-Fi-connected Bluetooth proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible.

substitutions:
  name: my-bluetooth-proxy

esphome:
  name: ${name}
  name_add_mac_suffix: true

esp32:
  variant: esp32
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  platform: esphome

esp32_ble_tracker:

bluetooth_proxy:
  active: true

ESP32 — Ethernet

A complete sample recommended configuration for an Ethernet-connected Bluetooth proxy. This configuration is not for a Wi-Fi-based proxy. If you experience issues with your proxy, try reducing your configuration to be as similar to this as possible.

This configuration is for an Olimex ESP32-PoE-ISO board with an Ethernet connection to the network. If you use a different board, you must change the board substitution to match your board.

substitutions:
  name: my-bluetooth-proxy
  board: esp32-poe-iso

esphome:
  name: ${name}
  name_add_mac_suffix: true

esp32:
  board: ${board}
  variant: esp32
  framework:
    type: esp-idf

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    mode: CLK_OUT
    pin: GPIO17
  phy_addr: 0
  power_pin: GPIO12

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  platform: esphome

esp32_ble_tracker:
  # The default scan parameters are recommended.
  # Aggressive scan settings (e.g., interval/window of 1100ms) typically
  # provide no benefit while increasing CPU usage and may cause
  # overheating on some PoE-based proxies.

bluetooth_proxy:
  active: true
  connection_slots: 4

LibreTiny — BK72xx / LN882H

A LibreTiny hub is Wi-Fi-only and proxies advertisements only. Because WiFi and BLE share a single CPU core, this configuration starts scanning only once Home Assistant connects, which keeps the radio free for the initial handshake.

substitutions:
  name: my-bluetooth-proxy

esphome:
  name: ${name}
  name_add_mac_suffix: true

bk72xx:                  # or ln882x for the LN882H
  board: cb3s            # set to your module's board

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

# Enable logging
logger:

ota:
  platform: esphome

bk72xx_ble_tracker:      # or ln882h_ble_tracker
  scan_parameters:
    continuous: false    # WiFi/BLE share one core — start scanning only when HA connects

bluetooth_proxy:

# Enable Home Assistant API and drive scanning from its connection state
api:
  on_client_connected:
    - bk72xx_ble_tracker.start_scan:
        continuous: true
  on_client_disconnected:
    - bk72xx_ble_tracker.stop_scan:

Troubleshooting

Memory issues (ESP32)

If you experience memory issues on ESP32, consider the following:

Framework: The esp-idf framework is recommended over arduino as it uses less memory.
NVS Partition Size: If you last updated your ESP32 via serial before 2022.12.0 on esp-idf or before 2026.4.0 on arduino it is recommended to update your partition table to increase the NVS partition size. You can do this by updating the device with a serial cable once or through an OTA partition table update.
Web Server: The Web Server component uses additional RAM. Disabling it can help if you experience memory-related issues.

Device compatibility

Not all BLE devices are supported and ESPHome does not decode or keep a list. To find out if your device is supported, please search for it in the Home Assistant Integrations list.