蓝牙代理

Home Assistant 可以通过 ESPHome 中的蓝牙代理组件进行通信来扩展其蓝牙覆盖范围。Home Assistant 中的各个设备集成（例如 BTHome）将接收来自 Home Assistant 中的蓝牙集成的数据，该蓝牙集成会自动聚合所有 ESPHome 蓝牙代理以及您可能拥有的任何 USB 蓝牙适配器。这个出色的功能在蓝牙设备和 Home Assistant 之间提供容错连接。

请注意，虽然此组件的名称是 bluetooth_proxy，但只支持 BLE 设备（及其 Home Assistant 集成）。

如果您想购买现成的蓝牙代理或自行刷写设备，请参阅支持蓝牙代理的 ESPHome 工程。

配置

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

active (可选, boolean)：启用对 BLE 设备的活动 GATT 连接代理。这与活动扫描（在 ESP32 BLE Tracker 中配置）是分开的。默认为 true。
cache_services (可选, boolean)：启用将 GATT 服务缓存到 NVS 闪存存储中，这能显著加快活动连接的速度。默认为 true。
connection_slots (可选, int)：要使用的最大 BLE 连接槽数量。每个配置的槽大约消耗 ~1KB RAM，最大为 9。建议不要超过 5 个连接槽，以避免稳定性和内存问题。默认为 3。基于以太网的代理通常可以稳定处理 4 个连接槽。该值不得超过 ESP32 BLE 配置的总 max_connections。

蓝牙代理依赖 ESP32 BLE Tracker，因此请确保将其添加到您的配置中。

活动连接的工作原理

蓝牙代理为 Home Assistant 提供有限数量的同时活动 GATT 连接（通过 connection_slots 配置）。默认是 3 个槽。基于以太网的代理通常可以稳定处理 4 个槽，因为它们不与 Wi-Fi 流量共享无线电。如果您需要更多连接，请设置 connection_slots: 4（每个槽使用额外的 RAM）。

持续保持连接的设备（如某些锁或恒温器）会一直占用一个槽。短暂连接以交换数据然后断开的设备（如许多传感器）会释放槽供其他设备使用，因此您可以使用的设备数量可以超过槽的数量。

被动广播的传感器数据（由不需要活动连接的设备广播，例如许多 BTHome 传感器）是单独接收的，不受连接槽数量的限制。

提高接收性能

使用带有以太网连接的开发板，将 ESP32 的无线电模块从 Wi-Fi 流量中解放出来，这可以提高蓝牙性能。为获得最佳效果，请使用带外部天线的开发板（例如，使用 Olimex ESP32-PoE-ISO-EA 而不是 Olimex ESP32-PoE-ISO）。

NOTE

默认扫描参数对大多数用户是推荐的。将 interval 或 window 从默认值更改通常不会带来有意义的收益，反而会增加 CPU 使用率和网络流量。激进的扫描设置可能导致基于 PoE 的代理过热，并导致基于 Wi-Fi 的代理 Wi-Fi 不稳定。

被动扫描与主动扫描

被动扫描适用于大多数 BLE 设备，足以满足日常运行。主动扫描会向设备请求额外的扫描响应数据，通常只在最初向 Home Assistant 添加新设备时才有需要。主动扫描还会增加电池供电的 BLE 设备的电池消耗。

ESP32 BLE Tracker 组件默认为主动扫描（active: true）。如果您遇到过热问题，并且您的设备不需要主动扫描，可以尝试切换到被动扫描：

esp32_ble_tracker:
  scan_parameters:
    active: false

避免将 ESP 节点放置在机架中、靠近路由器/交换机或其他网络设备，因为 EMI 干扰会降低蓝牙信号接收质量。为获得最佳效果，请尽可能远离，距离任何此类设备至少 3 米。将您的 ESPHome 设备放置在离您想要交互的蓝牙设备较近的位置，以获得最佳体验。

适用于 Wi-Fi 连接的蓝牙代理的完整推荐示例配置

下面是一个适用于 Wi-Fi 连接的蓝牙代理的完整推荐示例配置。如果您的代理出现问题，请尝试将您的配置尽量缩减得与此类似。

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

适用于以太网连接的蓝牙代理的完整推荐示例配置

下面是一个适用于以太网连接的蓝牙代理的完整推荐示例配置。此配置不是针对基于 Wi-Fi 的代理。如果您的代理出现问题，请尝试将您的配置尽量缩减得与此类似。

此配置适用于带有以太网连接的 Olimex ESP32-PoE-ISO 开发板。如果您使用不同的开发板，必须将 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

故障排除

内存问题

如果您遇到内存问题，请考虑以下几点：

框架： 推荐使用 esp-idf 框架而不是 arduino，因为它使用的内存更少。
NVS 分区大小： 如果您最后一次通过串口更新 ESP32 是在 esp-idf 上的 2022.12.0 之前，或是在 arduino 上的 2026.4.0 之前，建议您更新分区表以增大 NVS 分区大小。您可以通过使用串口线更新设备一次或通过 OTA 分区表更新来实现。
Web 服务器： Web Server 组件会使用额外的 RAM。如果您遇到与内存相关的问题，禁用它可能会有所帮助。

设备兼容性

并非所有 BLE 设备都受支持，ESPHome 不会解码或维护设备列表。要了解您的设备是否受支持，请在 Home Assistant 集成列表中搜索它。