Bluetooth Low Energy ma niewielki zasięg, a serwer z Home Assistantem stoi zwykle w szafce przy routerze, daleko od termometrów i czujników w doniczkach, z których ma odbierać dane. Dokumentacja Home Assistanta radzi na to nie lepszy adapter USB, tylko tanie ESP32 z ESPHome. Stawiasz płytkę w pokoju, w którym naprawdę są urządzenia Bluetooth, a ona przekazuje do Home Assistanta przez sieć wszystko, co usłyszy.

Z poradnika dowiesz się, co taki pośrednik potrafi, a czego nie, jaką płytkę kupić, jak wygląda konfiguracja zalecana przez ESPHome i jakie błędy w rozmieszczeniu i ustawieniach sprawiają, że działa gorzej, niż mógłby.

Jak działa pośrednik Bluetooth

Pośrednik Bluetooth (w dokumentacji „Bluetooth proxy”, a w Home Assistancie także zdalny adapter) to urządzenie sieciowe, które odbiera sygnały Bluetooth blisko obsługiwanych urządzeń i przesyła je do Home Assistanta przez Wi-Fi albo Ethernet. Integracja Bluetooth w Home Assistancie łączy wszystkie pośredniki i lokalne adaptery w jedną pulę, więc integracjom takim jak BTHome, Xiaomi BLE czy SwitchBot jest obojętne, który z nich odebrał sygnał. Jeśli w zasięgu jest kilka pośredników, integracje napisane zgodnie z wytycznymi dla autorów bibliotek łączą się przez ten, który ma najlepszy sygnał, a gdy zniknie, przełączają się na inny.

Przez pośrednik płyną dwa rodzaje danych:

  • Rozgłoszenia. To krótkie pakiety, którymi urządzenie ogłasza swoją obecność, często razem z odczytami z czujnika. Tak działa wiele termometrów i wszystkie urządzenia BTHome. Nie trzeba nawiązywać połączenia, odbierze je każdy skaner w zasięgu, a limit połączeń nie ma tu znaczenia.
  • Aktywne połączenia. To dwukierunkowe łącze GATT, przez które Home Assistant odczytuje dane z urządzenia albo wysyła mu polecenia. Potrzebują go na przykład niektóre zamki, termostaty i sterowniki LED. Każde takie połączenie zajmuje w pośredniku jedno miejsce.

Obsługiwane jest tylko BLE. Mimo nazwy komponentu bluetooth_proxy urządzenia ze starszym Bluetooth Classic nie będą przez niego działać, a integracja Bluetooth w Home Assistancie w ogóle ich nie obsługuje.

Czemu nie wystarczy adapter USB?

Może wystarczyć, zwłaszcza w jednym pokoju. Dokumentacja Home Assistanta otwarcie wymienia jednak wady: aktualizacje jądra Linuksa już wcześniej psuły obsługę Bluetooth, sterowniki do nowszych adapterów trafiają do Linuksa później niż do innych systemów, a jeśli Home Assistant działa w maszynie wirtualnej, przekazywanie urządzeń USB dokłada własne kłopoty. Dlatego w wielu przypadkach dokumentacja zaleca właśnie pośrednik na ESP32.

Liczy się też wydajność. Home Assistant szereguje rodzaje skanerów od najlepszego do najgorszego i na samej górze stawia pośrednik ESPHome podłączony przez Ethernet ze skanowaniem pasywnym, wyżej niż wydajny adapter USB. Pośrednik na Wi-Fi ze skanowaniem pasywnym jest trzeci. Wbudowany moduł Bluetooth typowego minikomputera czy Raspberry Pi jest blisko końca listy.

Jaką płytkę wybrać

Ważniejszy od producenta płytki jest układ, na którym ją zbudowano.

  • Zwykłe ESP32 (ESP32-WROOM-32 i podobne). Najbezpieczniejszy wybór. Instalator w przeglądarce na stronie ESPHome ma gotowy projekt pośrednika dla płytki „Generic ESP32” i w opisie zaznacza, że działa on tylko na zwykłym ESP32, a nie na ESP32-C3 i innych odmianach.
  • ESP32-S2. Nie nada się. Ma tylko Wi-Fi, nie ma radia Bluetooth.
  • ESP32-C3 i inne układy jednordzeniowe. Mogą działać, ale ESPHome ostrzega, że Wi-Fi i skaner BLE muszą wtedy dzielić jeden rdzeń, co powodowało kłopoty z łączeniem się z Wi-Fi. Dokumentacja podaje obejście: skanuj tylko wtedy, gdy Home Assistant jest połączony przez API.
  • Płytki z Ethernetem. Dają najlepsze wyniki, bo radio nie musi dzielić czasu nadawania z ruchem Wi-Fi. Zespół odpowiedzialny za Bluetooth w Home Assistancie rozwija i testuje pośrednik na płytce Olimex ESP32-POE-ISO-EA, a wersja „-EA” z zewnętrzną anteną ma wyraźnie lepsze parametry radiowe niż zwykła. Na stronie z projektami ESPHome znajdziesz też GL.iNet GL-S10, LilyGO T-ETH-POE, WT32-ETH01 i przystawkę Ethernet Seeed Studio XIAO W5500 (tylko płytki V1.2, produkowane po 1 listopada 2025). Część z nich wymaga dodatkowych kroków przy wgrywaniu oprogramowania, więc najpierw przeczytaj uwagi na tej stronie.

Jako pośrednik mogą też działać urządzenia Shelly Gen2+ i SMLIGHT SLZB-U, ale tylko dla rozgłoszeń. Jeśli potrzebujesz aktywnych połączeń, zostań przy ESPHome na ESP32.

Najszybciej: instalacja z przeglądarki

Jeśli chcesz po prostu mieć działający pośrednik na zwykłym ESP32, nie musisz pisać ani linijki YAML:

  1. Otwórz stronę z gotowymi projektami na esphome.io w przeglądarce Chrome, Edge albo Firefox (potrzebna jest obsługa WebSerial) i wybierz projekt Bluetooth proxy.
  2. Wybierz płytkę, podłącz ją przez USB i uruchom instalację.
  3. Gdy instalator o to poprosi, podaj nazwę i hasło sieci Wi-Fi.
  4. W Home Assistancie przejdź do Ustawienia > Urządzenia oraz usługi (po angielsku „Settings > Devices & services”). Nowe urządzenie ESPHome powinno się tam pojawić jako wykryte. Dodaj je.

To cała konfiguracja. Jeśli później zechcesz zmienić ustawienia, możesz przejąć urządzenie w panelu ESPHome. Płytki z Ethernetem zainstalowane w ten sposób mają wyłączone Wi-Fi i trzeba je podłączyć kablem.

Własna konfiguracja

Jeśli korzystasz już z panelu ESPHome albo chcesz dodać pośrednik do urządzenia, które zbudowałeś sam, zacznij od konfiguracji bardzo zbliżonej do tej, którą ESPHome zaleca dla pośrednika na 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

logger:

api:
  encryption:
    key: !secret encryption_key

ota:
  platform: esphome

esp32_ble_tracker:

bluetooth_proxy:
  active: true

Kilka linijek wymaga komentarza:

  • framework: type: esp-idf, bo ESP-IDF zużywa mniej pamięci niż Arduino, a obsługa BLE potrzebuje dużo RAM.
  • name_add_mac_suffix: true dokleja do nazwy fragment adresu MAC, dzięki czemu ten sam plik wgrasz na kilka płytek i nazwy nie będą się powtarzać.
  • Sekcja esp32_ble_tracker: jest obowiązkowa, bo pośrednik z niej korzysta.
  • active: true włącza aktywne połączenia GATT. Na ESP32 to i tak ustawienie domyślne, ale wpisane wprost od razu pokazuje, o co chodzi. Jeśli chcesz pośrednik, który tylko odbiera rozgłoszenia, ustaw false.
  • Blok encryption w sekcji api: nie jest obowiązkowy, ale jeśli go dodasz, Home Assistant poprosi o ten sam klucz przy dodawaniu urządzenia. Przykład w dokumentacji ESPHome go zawiera.

Gdy pierwszy raz dodajesz esp32_ble_tracker na danej płytce, wgraj oprogramowanie przez USB. Partycja z kodem musi zmienić rozmiar, a potem aktualizacje przez sieć (OTA) znowu działają normalnie.

Na płytce z Ethernetem zamień sekcję wifi: na odpowiednią sekcję ethernet:. W dokumentacji ESPHome jest pełny przykład dla płytki Olimex ESP32-POE-ISO z układem PHY LAN8720, w którym ustawiono connection_slots: 4.

Ile równoczesnych połączeń potrzebujesz

Każde miejsce na połączenie (connection_slots) to jedno aktywne połączenie w danej chwili. Na ESP32 domyślnie są 3, a maksymalnie 9, ale ESPHome zaleca nie przekraczać 5, bo każde miejsce zajmuje około 1 KB RAM, a przy większej liczbie pojawiają się problemy z pamięcią i stabilnością. Pośrednik na Ethernecie zwykle bez kłopotu obsłuży 4, bo nie dzieli radia z Wi-Fi. Wartość nie może być większa niż max_connections w komponencie esp32_ble, który domyślnie też ma 3, więc jeśli podnosisz jedno, podnieś i drugie.

Urządzeń możesz mieć więcej, niż jest miejsc. Sprzęt, który utrzymuje połączenie bez przerwy, jak niektóre zamki czy termostaty, zajmuje miejsce cały czas. Czujnik, który łączy się na chwilę, wymienia dane i się rozłącza, zwalnia miejsce dla kolejnego urządzenia. Czujniki, które tylko rozgłaszają dane, w ogóle nie zajmują miejsc.

Najpierw miejsce montażu, potem ustawienia

Zanim zaczniesz zmieniać konfigurację, sprawdź, gdzie stoi płytka.

  • Postaw pośrednik blisko urządzeń Bluetooth, które ma obsługiwać. Jeśli są rozrzucone po różnych pokojach i piętrach, daj osobny pośrednik do każdej części domu, zamiast próbować objąć wszystko z jednego miejsca.
  • Trzymaj go co najmniej 3 metry od routerów, przełączników sieciowych i innego sprzętu sieciowego i nie montuj go w szafie serwerowej. Zakłócenia elektromagnetyczne z tych urządzeń pogarszają odbiór Bluetooth.
  • Jeśli masz kilka pośredników, rozstaw je na tyle daleko od siebie, żeby się nawzajem nie zakłócały.
  • Jeśli wciąż działa stary, słaby adapter, rozważ jego wyłączenie. Home Assistant wybiera drogę połączenia według siły sygnału i wolnych miejsc na połączenia, a dokumentacja ostrzega, że słaby adapter z najlepszym sygnałem może ograniczyć wydajność.

Nie ruszaj parametrów interval i window w ustawieniach skanowania. Według ESPHome wartości domyślne pasują większości użytkowników, a agresywne ustawienia zwykle nic nie dają, za to zwiększają obciążenie procesora i ruch w sieci. Na pośrednikach zasilanych przez PoE mogą powodować przegrzewanie, a na tych z Wi-Fi niestabilne połączenie.

Skanowanie aktywne, pasywne i automatyczne

Aktywne połączenia to jedno, a aktywne skanowanie to drugie. Przy aktywnym skanowaniu pośrednik prosi urządzenia o dodatkowe dane (odpowiedź na skanowanie). Wykrywanie idzie wtedy szybciej, ale urządzenia na baterie szybciej się rozładowują. W aktualnych wersjach Home Assistanta tryb ustawiasz osobno dla każdego pośrednika: w Ustawienia > Urządzenia oraz usługi otwórz urządzenie ESPHome i wybierz Konfiguruj („Configure”). Domyślny tryb automatyczny („Auto”) przez większość czasu nasłuchuje pasywnie i przechodzi na skanowanie aktywne tylko wtedy, gdy integracja potrzebuje więcej danych. Według Home Assistanta w porównaniu z ciągłym skanowaniem aktywnym oszczędza to około 95-96 procent energii, którą urządzenia na baterie tracą przez skanowanie. Zostaw tryb automatyczny, chyba że któraś integracja przestanie działać.

Gdy Home Assistant raz zapisze tryb skanowania, od tej pory to on nim zarządza. Zmiana trybu w pliku YAML urządzenia nie wpływa już na działający pośrednik, co potrafi zdziwić, jeśli edytujesz plik i nie widzisz efektów.

Jak sprawdzić, czy działa

Otwórz w ustawieniach sekcję łączności i Bluetooth („Settings > Connectivity > Bluetooth”). W widoku adapterów („Adapters”) zobaczysz wszystkie skanery, lokalne i zdalne, z ich stanem i możliwościami, a mapa sieci pokaże, przez który skaner dane urządzenie łączy się z Home Assistantem. Podgląd rozgłoszeń („Advertisement Monitor”) wyświetla rozgłoszenia odbierane w zasięgu, a podgląd połączeń („Connection Monitor”) aktywne połączenia.

Jeśli jakieś urządzenie się nie pojawia, sprawdź, czy Home Assistant ma dla niego integrację. ESPHome nie dekoduje danych z urządzeń BLE ani nie prowadzi listy obsługiwanego sprzętu. Pośrednik tylko przekazuje dane, a odczytuje je integracja w Home Assistancie.

Typowe problemy

  • Ponowne uruchomienia i zawieszanie się po dodaniu kolejnych funkcji. Obsługa BLE zajmuje dużo RAM. Niech pośrednik będzie tylko pośrednikiem: unikaj komponentów, które potrzebują dużo pamięci, takich jak asystent głosowy czy obsługa dźwięku, używaj esp-idf i rozważ wyłączenie wbudowanego serwera WWW (web_server).
  • Problemy z pamięcią na starszej płytce. Jeśli ostatni raz wgrywałeś oprogramowanie przez port szeregowy przed ESPHome 2022.12.0 na esp-idf (albo przed 2026.4.0 na Arduino), zaktualizuj tablicę partycji, żeby dostać większą partycję NVS. Możesz to zrobić raz przez USB albo aktualizacją tablicy partycji przez sieć (OTA).
  • Zrywanie Wi-Fi na ESP32-C3. Skorzystaj z obejścia dla układów jednordzeniowych z dokumentacji ESPHome, które włącza skanowanie dopiero po połączeniu klienta API, albo przesiądź się na dwurdzeniowe ESP32.
  • Czujniki na baterie szybko się rozładowują. Sprawdź, czy pośrednik nie został na stałe w trybie aktywnego skanowania („Active”).