Bluetooth Proxy в Home Assistant: настройка ESP32, ESPHome и подключение BLE-устройств

Что такое Bluetooth Proxy в Home Assistant

Bluetooth Proxy — сетевой адаптер Bluetooth Low Energy (BLE). Обычно это небольшая плата с ESPHome, которая улавливает радиопакеты от находящихся рядом датчиков и передаёт их Home Assistant через Wi-Fi либо Ethernet. Для некоторых устройств прокси также устанавливает активное GATT-соединение и позволяет выполнять команды.

Прокси не работает как Zigbee-роутер и не создаёт отдельную Bluetooth mesh-сеть. Это удалённый Bluetooth-сканер, который использует обычную IP-сеть, чтобы передавать данные Home Assistant. Если на сервере уже есть USB Bluetooth-адаптер, их можно использовать параллельно.

Когда Bluetooth Proxy действительно нужен

• Home Assistant работает в серверной, а BLE-термометры и датчики находятся в дальних комнатах.
• Дом двухэтажный, а железобетонные перекрытия мешают приёму от батарейных датчиков.
• Home Assistant установлен в виртуальной машине либо Docker без удобной передачи USB-адаптера.
• Нужно принимать BTHome или Xiaomi BLE broadcasts из нескольких частей дома.
• Некоторые замки, термостаты и другие устройства требуют активного GATT-подключения через поддерживающую это интеграцию.

Если BLE-устройства уже стабильно работают от встроенного адаптера на сервере, отдельный прокси не даст обязательного улучшения. Изменение архитектуры имеет смысл при проблемах покрытия, расположения сервера или числа активных соединений.

Bluetooth Proxy, Zigbee и Matter Bridge — не одно и то же

О сравнении радиопротоколов и интеграциях рассказывают ZHA или Zigbee2MQTT и как работает Matter Bridge. Наличие Matter на упаковке устройства не означает, что к нему нужен Bluetooth Proxy: BLE у некоторых Matter-устройств применяется лишь во время первичного подключения.

BLE advertisements и активное GATT-соединение

При выборе оборудования важно различать два режима работы BLE:

Режим active scan означает отправку scan requests для получения дополнительных рекламных данных, а active: true у bluetooth_proxy — разрешение GATT-соединений. Это разные настройки и их нельзя путать.

Что выбрать: ESP32, Ethernet, Raspberry Pi Pico W

Не все платы ESP32 одинаковы. Официальный готовый проект ESPHome Generic ESP32 предназначен для классического ESP32, а не для любого ESP32-C3/S3. Для другой платы выбирайте сборку и board profile по её документации.

Connection slots: сколько устройств можно подключить одновременно

Количество активно подключённых устройств ограничивается слотами. Для ESP32 Bluetooth Proxy значение connection_slots по умолчанию составляет 3. Для RP2040/RP2350 максимум также равен трём. На ESP32 поддерживается максимум девять слотов, но ESPHome рекомендует обычно не превышать пяти из-за памяти и стабильности. Ethernet-прокси нередко выдерживает четыре слота.

Устройство, постоянно удерживающее GATT-соединение, занимает слот всё время. Кратковременно опрашиваемые устройства освобождают слот после обмена. Пассивные advertising-датчики BTHome слот активного GATT не занимают.

Wi-Fi против Ethernet и PoE для Bluetooth Proxy

Если прокси должен находиться в слабой Wi-Fi-зоне, лучше обеспечить качественную беспроводную сеть или использовать Ethernet. Однако PoE-кабель сам по себе не решает проблему BLE-приёма, если прокси спрятан за металлом.

Где размещать BLE-прокси в квартире или доме

• Ближе к проблемным датчикам, а не обязательно рядом с сервером.
• Не внутри металлического электрощита, серверного шкафа или закрытого корпуса без рассчитанной антенны.
• На стабильном источнике питания с нормальным охлаждением и безопасным размещением.
• Не вплотную к мощным 2,4-ГГц передатчикам и помехообразующему оборудованию.
• Для двухэтажного дома попробуйте отдельный прокси на разных уровнях, но не ставьте несколько плат в нескольких сантиметрах друг от друга.

Не существует гарантированной «дальности ESP32 30 метров»: она зависит от устройства, антенны, стен, расположения и препятствий. Проверяйте покрытие практически, наблюдая частоту поступления данных и пропадания устройств.

Способ №1: установить готовую прошивку Bluetooth Proxy без YAML

Официальный сайт ESPHome предоставляет Ready-Made Projects. Для совместимых устройств можно прошить Bluetooth Proxy через браузер с поддержкой WebSerial, не создавая YAML вручную.

Способ №2: минимальный YAML для классического ESP32

Следующий пример предназначен для совместимой платы типа ESP32 DevKit (ESP32-WROOM) с Wi-Fi. Это пример нового устройства, а не универсальная замена конфигурации любого ESP32. Для другого типа board, framework или Ethernet используйте профиль конкретной платы.

esphome:
  name: ble-proxy-hall
  friendly_name: "BLE Proxy Hall"

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: !secret ble_proxy_hall_api_key

ota:
  - platform: esphome
    encryption:

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

esp32_ble_tracker:

bluetooth_proxy:

Имена секретов должны быть созданы в secrets.yaml соответствующего ESPHome Device Builder. Ключ Native API представляет собой корректный base64-ключ, а не произвольный короткий пароль. Для OTA выбран актуальный формат платформы esphome с шифрованием, использующим API-ключ. Не копируйте пример поверх рабочей конфигурации устройства с GPIO и исполнительными выходами.

Пароли Wi-Fi, API encryption и OTA

Используйте отдельные секреты для SSID, Wi-Fi-пароля и ключа Native API. Не публикуйте secrets.yaml в открытом репозитории и не пересылайте конфигурации с действующим API-ключом без редактирования.

wifi_ssid: "My-IoT-WiFi"
wifi_password: "REPLACE_WITH_REAL_WIFI_PASSWORD"
ble_proxy_hall_api_key: "REPLACE_WITH_VALID_BASE64_KEY"

В актуальной документации ESPHome рекомендовано шифрование OTA тем же ключом, который используется Native API, если конфигурация уже настроена под этот режим. Для существующего устройства с другим механизмом OTA миграцию сначала проверяйте по документации, чтобы не потерять доступ к обновлениям.

Как прокси появляется в Home Assistant

После запуска ESPHome-устройство должно добавиться через Settings → Devices & services → ESPHome. Если обнаружение работает, Home Assistant предложит настроить новое устройство. В отдельных сетях с VLAN/mDNS потребуется ручное добавление по IP-адресу.

На уровне Home Assistant прокси работает через интеграцию Bluetooth, которая объединяет данные нескольких сканеров, в том числе локальных USB-адаптеров. BLE-датчик может появиться как обнаруженное устройство для отдельной интеграции: BTHome, Xiaomi BLE, SwitchBot, Ruuvi и других.

Не пытайтесь добавлять каждый BLE-датчик как отдельное ESPHome-устройство. Сам прокси принадлежит ESPHome, а датчик подключается через собственную integration в Home Assistant.

BTHome: как подключить передающие данные BLE-датчики

BTHome — формат BLE advertising, в котором датчики могут передавать измерения без постоянного GATT-соединения. Интеграция BTHome в Home Assistant автоматически обнаруживает совместимые устройства, если Bluetooth работает и пакет дошёл до сканера.

• Проверьте питание сенсора и то, что он действительно передаёт BTHome в эфир.
• Убедитесь, что Bluetooth Proxy подключён к Home Assistant.
• В Settings → Devices & services найдите обнаруженный BTHome device.
• Если сенсор шифрует advertising, интеграция запросит bindkey — 16-байтный ключ в формате 32 hex символа.

Покупка «Bluetooth-датчика» ещё не гарантирует совместимость с BTHome. Устройства могут использовать проприетарные данные, другую систему шифрования или требовать собственного облака.

Как включить или отключить активные GATT-соединения

На платформах с поддержкой активных соединений параметр active: true у Bluetooth Proxy разрешает GATT. На ESP32 и совместимых RP2-платформах это значение по умолчанию включено. Если вам нужен лишь сбор BLE advertisements, можно выключить GATT:

esp32_ble_tracker:

bluetooth_proxy:
  active: false

В этом режиме прокси по-прежнему принимает BLE-пакеты, но через него нельзя устанавливать активные соединения с BLE-устройствами. На платформах BK72xx/LN882x GATT-подключения не поддерживаются в принципе, поэтому указание active: true вызовет ошибку валидации.

Расширение числа одновременных соединений: пример для ESP32 Ethernet

Если у вас действительно имеется подходящая ESP32 Ethernet-плата и устройства удерживают несколько активных GATT-соединений, можно увеличить slots до четырёх. Но только после проверки ресурсов и совместимости платы.

esp32_ble:
  max_connections: 4

esp32_ble_tracker:

bluetooth_proxy:
  active: true
  connection_slots: 4

Это только фрагмент для готовой рабочей конфигурации ESP32 с Ethernet, а не самостоятельная прошивка. Параметр max_connections в ESPHome 2026 перенесён в esp32_ble; старые гайды с ним внутри esp32_ble_tracker устаревают. Для обычного Wi-Fi-прокси сначала используйте стандартные три connection slots.

Auto, Active и Passive: режим сканирования BLE

Для ESPHome Bluetooth Proxy последних версий Home Assistant предоставляет выбор Auto, Active или Passive через настройки конкретного ESPHome-устройства. Рекомендуемое значение для большинства систем — Auto: прокси преимущественно слушает эфир пассивно и ненадолго включает активное сканирование, когда интеграции требуются дополнительные данные.

Active scanning увеличивает расход батарей BLE-устройств. Согласно документации Home Assistant, Auto может уменьшать связанную со сканированием нагрузку на батарейные датчики примерно на 95–96% по сравнению с постоянно активным сканированием. Это не означает экономию на 95% всего энергопотребления устройства.

Можно ли установить несколько Bluetooth Proxy

Да. Home Assistant агрегирует BLE-рекламные пакеты от нескольких сканеров, выбирая подходящие пути для поддерживаемых BLE-соединений. Это позволяет улучшить покрытие квартиры, разных этажей и удалённых помещений.

Количество сканеров ограничено прежде всего производительностью хоста и сети, а не фиксированным малым числом. Но установка трёх прокси вплотную друг к другу не даст тройного радиуса: их лучше разносить по реальным зонам приёма. Для активных GATT-устройств важны доступные connection slots и устойчивость конкретного пути.

Если датчики продолжат теряться, оцените не только RSSI, но и реальные пропуски измерений, совместимость выбранной интеграции и занятость слотов.

Работа в разных VLAN: mDNS, firewall и ESPHome API

ESPHome Proxy передаёт данные Home Assistant по IP-сети. Если прокси находится в IoT VLAN, а Home Assistant в другом сегменте, маршрутизация и правила firewall должны разрешать необходимые соединения. mDNS discovery в разных подсетях может потребовать отражателя либо ручной настройки устройства по IP.

Обычно для Native API ESPHome используется TCP 6053, но реальный порт определяется конфигурацией и версией. OTA также требует доступности выбранного механизма обновления. Не нужно ради обнаружения прокси полностью открывать IoT-сегмент в LAN.

Порядок работы с discovery и изоляцией подробно описан в материале Home Assistant и IoT в разных VLAN: mDNS, SSDP и Matter.

Прокси найден, но стал unavailable: что проверить

Если сам прокси постоянно отключается от Wi-Fi, сначала устраняйте сетевую проблему, а не перепривязывайте датчики. Инструкция по поиску первопричины в логах Home Assistant поможет отличить сетевую ошибку от ошибки integration.

Bluetooth Proxy онлайн, но датчики не появились

Помните: BLE advertising не является командой «передать данные немедленно». Батарейный сенсор может иметь собственный интервал публикации, и принудительное опрашивание через прокси не всегда поддерживается.

Датчики «отваливаются» и появляются снова

Для батарейных BLE-датчиков пропуск единичного advertising-пакета не обязательно означает полный отказ. Но регулярные пропадания на часы и ошибки GATT уже требуют диагностики.

• Проверьте расстояние, стены, корпус, положение платы и помехи в диапазоне 2,4 ГГц.
• Сопоставьте время ошибки и сообщения Bluetooth integration в Home Assistant.
• Не используйте металлический шкаф как место BLE-приёма.
• Установите прокси рядом с датчиком на время теста. Улучшение приёма позволит отделить проблему радиопокрытия от программной ошибки.
• Если GATT-соединение удерживается постоянно, оцените свободные slots и не увеличивайте их вслепую.

Причины нестабильности разных беспроводных датчиков подробно разобраны в статье почему радиодатчики отваливаются: стены, металл, батарейки и помехи.

Где смотреть BLE-логи ESPHome и Home Assistant

Диагностика обычно разделяется на два уровня: журнал самой ESPHome-платы и журнал интеграции Bluetooth/ESPHome в Home Assistant. В Device Builder ESPHome можно открыть logs устройства, а в Home Assistant включить временный debug для нужной integration.

logger:
  level: DEBUG
  logs:
    bluetooth_proxy: DEBUG
    bluetooth_connection: DEBUG

На платах с ограниченными ресурсами подробный лог может ухудшить стабильность и создать значительный поток сообщений. После воспроизведения проблемы верните нормальный уровень логирования и сохраните небольшой релевантный фрагмент.

Безопасность и обновления Bluetooth Proxy

• Не открывайте ESPHome API и OTA в интернет и не отключайте шифрование ради удобства.
• Используйте доверенные firmware и храните исходный YAML/секреты в защищённом месте.
• Обновляйте ESPHome после проверки совместимости конкретной платы и release notes.
• Не ставьте неподтверждённую прошивку на устройство, которое одновременно отвечает за отопление или реле.
• Помните, что прокси принимает радиоданные nearby BLE-устройств. Соблюдайте приватность пользователей и не используйте его для скрытого слежения.

Общие рекомендации по токенам, правам и сегментации собраны в материале Безопасность Home Assistant: MFA, токены и удалённый доступ.

Как проверить, что новый прокси действительно помогает

Для инженерных сценариев важнее проверяемое уменьшение пропусков, чем просто факт появления нового устройства в интерфейсе.

Типичные ошибки при настройке Bluetooth Proxy

• Покупать ESP32-C3/S3, рассчитывая применить готовую прошивку «Generic ESP32» без проверки совместимости.
• Считать bluetooth_proxy.active: true режимом активного сканирования вместо GATT.
• Пытаться включить активные соединения на платформах advertising-only.
• Увеличивать connection_slots выше ресурсов платформы или без согласования с max_connections.
• Ставить BLE Proxy внутрь металлического электрощита.
• Игнорировать нестабильное Wi-Fi и винить Bluetooth-датчики.
• Путать Home Assistant Bluetooth integration с ESPHome integration и пытаться добавить датчик как ESPHome node.
• Открывать API или OTA наружу через port forwarding.
• Перепрошивать существующий исполнительный контроллер без backup.
• Ожидать работу Bluetooth Classic аудио или любую проприетарную BLE-экосистему без подходящей интеграции.

Что в итоге выбрать для квартиры и частного дома

Если вы только начинаете работу с ESPHome, полезен материал ESPHome без пайки: устройства и локальная автоматика. Для понимания структуры integrations и devices в HA — entities, devices, areas и helpers.

FAQ: Bluetooth Proxy, ESPHome и Home Assistant

Официальная документация Home Assistant и ESPHome

Технические ограничения и синтаксис сверены с документацией на 9 октября 2026 года. При обновлении ESPHome или Home Assistant проверяйте release notes и особенности своей платы.

• Bluetooth integration — Home Assistant
• ESPHome integration — Home Assistant
• Bluetooth Proxy — ESPHome
• Ready-Made Projects — ESPHome
• ESP32 BLE Tracker — ESPHome
• ESP32 BLE component — ESPHome
• Native API — ESPHome
• ESPHome OTA
• BTHome — Home Assistant