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.

Configuration

bluetooth_proxy:
  # Active connections are enabled by default on ESP32 and RP2040/RP2350.
  # For an advertisement-only proxy, use:
  # active: false

active (Optional, boolean): Enables proxying active GATT connections to BLE devices. This is separate from active scanning (configured in your platform’s BLE tracker). Defaults to true on ESP32 and RP2040/RP2350. On advertisement-only platforms it defaults to false and enabling it fails validation — see Platform Support. RP2040/RP2350 proxies were advertisement only before active connection support landed, so existing Pico W configurations that omit this option will gain connection slots on their next update; set active: false to keep an advertisement-only proxy.
cache_services (Optional, boolean): ESP32 only; setting it on any other platform is a configuration error. Enables caching GATT services in NVS flash storage which significantly speeds up active connections. Defaults to true.
connection_slots (Optional, int): ESP32 and RP2040/RP2350. The maximum number of BLE connection slots to use. On RP2040/RP2350 the maximum and default are both 3; three slots use about 17KB more static RAM than a single-slot build. On ESP32, 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. The ESP32 default is 3. Ethernet-based proxies can generally handle 4 slots reliably. The value must not exceed the total configured max_connections for ESP32 BLE.

The Bluetooth proxy depends on the platform’s BLE tracker component, so make sure to add that to your configuration: ESP32 BLE Tracker on ESP32, the RP2 BLE Tracker on RP2040/RP2350, or the LN882H BLE Tracker on LN882x.

How Active Connections Work

The Bluetooth proxy provides Home Assistant with a limited number of simultaneous active GATT connections (configured via connection_slots). On ESP32 the default is 3 slots; Ethernet-based proxies can generally handle 4 slots reliably since they don’t share the radio with WiFi traffic, so set connection_slots: 4 there if you need more connections (each slot uses additional RAM). RP2040/RP2350 proxies also default to 3 slots, which is the platform maximum; lower connection_slots (1 or 2) to reclaim static 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.

Active connections are handled by the internal bluetooth_connection component, which is loaded automatically and has no configuration of its own. Its log lines use the bluetooth_connection tag, which is useful when filtering logs with the Logger component.

Platform Support

The proxy runs on platforms whose BLE hub can scan actively, and the feature set depends on what the controller can do beyond scanning:

ESP32 — the full proxy: advertisements plus active connections, so Home Assistant can read and write GATT characteristics through the device (active: true, connection_slots); requires the ESP32 BLE Tracker component.
RP2040/RP2350 (Raspberry Pi Pico W family) — the full proxy, with active connections through the framework’s BTstack GATT client; requires the RP2 BLE Tracker component. Up to 3 concurrent GATT connections are supported, matching the ESP32 default.
BK72xx and LN882x — advertisement-only. These controllers do not expose the GATT client the proxy needs for connections, so Home Assistant uses the device for advertisements only and will not route connections through it; requires the BK72xx BLE Tracker or LN882H BLE Tracker component. This is independent of the scan mode, which the platform’s tracker controls. Advertisement forwarding — which is what integrations such as BTHome, Xiaomi and most sensors rely on — works exactly as it does on ESP32.

On the advertisement-only platforms the proxy cannot be switched to active connections: active defaults to false there and setting active: true fails validation, as do the connection-oriented options (connection_slots, cache_services). The platform’s tracker hub must be part of the configuration — BK72xx BLE Tracker or LN882H BLE Tracker:

# Advertisement-only proxy on an LN882x board
ln882h_ble_tracker:

bluetooth_proxy:

NOTE

A scanner-mode request from Home Assistant (active or passive scanning) is honored on these platforms: the platform’s BLE tracker hub applies the requested mode, and a running scan restarts with the new mode.

Improving reception performance

Use a board with an Ethernet connection to the network to offload ESP32’s 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).

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.

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.

The ESP32 BLE Tracker component defaults to active scanning (active: true). If you experience overheating, you can try switching to passive scanning if your devices don’t require active scans:

esp32_ble_tracker:
  scan_parameters:
    active: false

Avoid placing the ESP 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 recommended configuration for a WiFi-connected Bluetooth proxy

Below is a complete sample recommended configuration for a WiFi-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

Complete sample recommended configuration for an ethernet-connected Bluetooth proxy

Below is 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

Troubleshooting

Memory Issues

If you experience memory issues, 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.