蓝牙代理

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

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

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

配置

bluetooth_proxy:
  # 活动连接现在默认启用
  # 要禁用活动连接（之前的默认行为），请使用：
  # active: false

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

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

活动连接的工作原理

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

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

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

改善接收性能

使用具有以太网连接的开发板连接到网络，以减轻 ESP32 无线电模块的 WiFi 流量负担，从而提高蓝牙性能。为获得最佳效果，请使用带有外部天线的开发板（例如，Olimex ESP32-PoE-ISO-EA 而非 Olimex ESP32-PoE-ISO）。

NOTE

默认扫描参数适用于大多数用户。更改 interval 或 window 的默认值通常没有任何实质性的好处，同时会增加 CPU 使用率和网络流量。激进的扫描设置可能导致基于 PoE 的代理过热，以及基于 WiFi 的代理出现 WiFi 不稳定。

被动扫描与活动扫描

被动扫描适用于大多数 BLE 设备，足以进行持续操作。活动扫描向设备请求额外的扫描响应数据，通常仅在最初向 Home Assistant 添加新设备时需要。活动扫描还会增加电池供电 BLE 设备的电池消耗。

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

esp32_ble_tracker:
  scan_parameters:
    active: false

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

WiFi 连接的蓝牙代理完整推荐配置示例

以下是 WiFi 连接的蓝牙代理的完整推荐配置示例。如果您的代理遇到问题，请尝试将您的配置简化为尽可能与此相似。

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

# 启用日志
logger:

# 启用 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

# 启用日志
logger:

# 启用 Home Assistant API
api:

ota:
  platform: esphome

esp32_ble_tracker:
  # 推荐使用默认扫描参数。
  # 激进的扫描设置（例如 interval/window 为 1100ms）通常
  # 没有任何好处，同时会增加 CPU 使用率，并可能导致
  # 某些基于 PoE 的代理过热。

bluetooth_proxy:
  active: true
  connection_slots: 4

故障排除

内存问题

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

框架： 推荐使用 esp-idf 框架而非 arduino，因为它使用更少的内存。切换框架时，请使用串口线更新设备，因为分区表不同。 OTA 更新不会更改分区表。
Web 服务器： Web 服务器组件使用额外的 RAM。如果您遇到与内存相关的问题，禁用它可能会有所帮助。

设备兼容性

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