Pełna kontrola - Tworzenie urządzeń Thread za pomocą ESPHome

Dzięki płytce rozwojowej ESP32 można tworzyć własne urządzenia inteligentnego domu, łącząc czujniki, diody LED, przyciski i inne elementy elektroniczne. Płytkę ESP32 można zaprogramować za pomocą platform open source, takich jak Arduino [1], MicroPython [2] lub ESPHome [3]. ESPHome, który opisałem we wcześniejszym artykule Linux Magazine [4] i o którym napisałem książkę [5], jest szczególnie interesujący, ponieważ obsługuje natywne API Home Assistanta [6]. Pozwala to na łatwą i wydajną integrację z tym popularnym rozwiązaniem open source dla inteligentnych bramek domowych.

Jeśli tworzysz inteligentne urządzenie domowe oparte na ESP32, zwykle wykorzystuje ono Wi-Fi. Jednak sieć Wi-Fi w domu może być już dość zajęta. Na szczęście istnieją alternatywy dla Wi-Fi. T

hread [7, 8] jest jedną z takich opcji: Thread to bezprzewodowa sieć mesh zoptymalizowana pod kątem urządzeń zasilanych bateryjnie o niskim zapotrzebowaniu na przepustowość. Jest to idealne rozwiązanie dla czujników temperatury, przycisków i nie tylko.

Od wersji 2025.6 ESPHome obsługuje również komunikację z Home Assistantem za pośrednictwem sieci Thread. W tym artykule zilustruję to od podstaw: skonfigurujesz własny router Thread Border Router, połączysz go z Home Assistantem i utworzysz urządzenia ESPHome z czujnikami, diodami LED i przyciskami działającymi w sieci Thread.

Zakładam, że zainstalowałeś już Home Assistanta. Jeśli nie, instrukcje dotyczące konfiguracji [9] można znaleźć na stronie internetowej projektu. W tym artykule użyłem instalacji Home Assistant Operating System (HA OS) na Raspberry Pi 4 i nie testowałem innych typów instalacji; mogą one działać, ale prawdopodobnie wymagają pewnych minimalnych zmian w podejściu wyjaśnionym w tym artykule.

Router graniczny – Thread Border Router

Po pierwsze, potrzebny jest router Thread Border Router. Urządzenie to umożliwia komunikację między siecią Thread a resztą sieci lokalnej (WiFi i/lub Ethernet). Możesz już mieć router graniczny w domu, taki jak Apple HomePod mini lub Google Nest Wifi Pro. Alternatywnie możesz stworzyć router graniczny OpenThread [10] z Raspberry Pi i kluczem sprzętowym nRF52840 lub router graniczny Espressif Thread [11] wykorzystujący płytkę rozwojową Espressif z ESP32-S3 (dla WiFi) i ESP32-H2 (dla Thread).

Do tego testu wybrałem dodatek OpenThread Border Router w Home Assistancie w połączeniu z kluczem Home Assistant Connect ZBT-1 [12], wcześniej znanym jako Home Assistant SkyConnect. Zawiera on układ radiowy obsługujący zarówno Thread, jak i Zigbee (w listopadzie 2025 roku ukazała się jego nowa wersja – ZBT-2). Podłącz klucz sprzętowy za pomocą przedłużacza USB do komputera z uruchomionym Asystentem Domowym (rysunek 1), najlepiej do portu USB 2.0, aby zminimalizować zakłócenia (patrz ramka "Zakłócenia związane z USB 3.0").

Rysunek 1: Aby uzyskać lepszą jakość sygnału, zawsze podłączaj klucz radiowy Thread za pomocą przedłużacza USB.

Dodatek OpenThread Border Router

Przejdź do ustawień Home Assistant w sekcji Urządzenia i usługi, a nowo odkryty klucz sprzętowy znajdziesz w zakładce Integracje. Kliknij na Dodaj obok niego. Następnie zostaniesz zapytany, czy chcesz skonfigurować z nim sieć Zigbee czy Thread. Klucz sprzętowy obsługuje oba protokoły bezprzewodowe, a wybór określa, które oprogramowanie sprzętowe zostanie sflashowane do urządzenia. Wybierz Threadi poczekaj kilka minut. Home Assistant najpierw zainstaluje dodatek OpenThread Border Router, a następnie sflashuje odpowiednie oprogramowanie sprzętowe do klucza sprzętowego. Następnie można przypisać pomieszczenie do routera granicznego. Jest to opcjonalne i nie jest konieczne dla sieci Thread.

Skonfigurowane integracje mają teraz dwa nowe dodatki: Home Assistant Connect ZBT-1 i Open Thread Border Router. Zobaczysz również nowo odkrytą integrację: Thread. Kliknij Dodaj tutaj i potwierdź, że chcesz skonfigurować integrację. Nie ma potrzeby dokonywania dodatkowych wyborów, ponieważ integracja automatycznie korzysta z zainstalowanego routera granicznego. Jeśli następnie klikniesz Thread w skonfigurowanych integracjach, a następnie ikonę koła zębatego pod skonfigurowaną usługą, zobaczysz sieć z jednym routerem granicznym. Kliknij ikonę informacji obok niego, aby wyświetlić właściwości sieci, których użyjesz później do podłączenia urządzeń ESPHome do tej sieci.

Płytki ESP32 z Thread

Aby komunikować się za pośrednictwem sieci Thread, potrzebny jest specjalny układ radiowy, który implementuje warstwę łącza sieci IEEE 802.15.4. W Home Assistant Connect ZBT-1 tym układem jest Silicon Labs EFR32MG21. Typowe płytki rozwojowe ESP32 nie obsługują Thread, ale ESP32-C6 i ESP32-H2 już tak. ESP32-C6 obsługuje również Wi-Fi 6. W przypadku aplikacji zasilanych bateryjnie ESP32-H2 jest bardziej odpowiedni, ponieważ Wi-Fi zużywa więcej energii. W przypadku tego artykułu nie ma to jednak większego znaczenia, ponieważ ESPHome nie obsługuje jeszcze funkcji niskiego zużycia energii Thread. Przetestowałem tę konfigurację z dwiema różnymi płytkami rozwojowymi, obie z ESP32-H2 (rysunek 2):

• f ESP32-H2-DEV-KIT-N4 od Waveshare mierzy 51,6 mm na 25,4 mm, z dwoma rzędami 15 pinów, diodą LED WS2812B RGB i portem USB-C. Można go nabyć z przylutowanymi pinami lub bez nich.
• f Super Mini ESP32-H2 od Shenzhen Hongwei Microelectronics to niewielka płytka o wymiarach 23,5 mm na 18 mm, z dwoma rzędami dziewięciu pinów, niebieską diodą LED, diodą WS2812 RGB LED i portem USB-C. Dostarczana jest z pinami, które należy samodzielnie przylutować.

Rysunek 2: Super Mini ESP32-H2 (po lewej) i ESP32-H2-DEV-KIT-N4 (po prawej) to idealne płytki rozwojowe do eksperymentowania z OpenThread w ESPHome.

Instalacja ESPHome

Gdy sieć Thread jest gotowa i masz odpowiednie płytki ESP32, nadszedł czas, aby zainstalować ESPHome, aby je zaprogramować. ESPHome składa się z dwóch komponentów: oprogramowania układowego, które jest instalowane na ESP32, i systemu, który działa na komputerze w celu zbudowania oprogramowania układowego w oparciu o konfigurację urządzenia. Ten drugi komponent można uruchomić na własnym komputerze, ale na potrzeby tego artykułu wybrałem łatwy do zainstalowania dodatek ESPHome Device Builder [14] dla Home Assistant.

W ustawieniach Home Assistant kliknij Add-ons, a następnie niebieski przycisk Add-on store w prawym dolnym rogu. Wybierz ESPHome Device Builder w kategorii ESPHome i kliknij Install. Po zakończeniu instalacji włącz Pokaż na pasku bocznym, kliknij Uruchom, a następnie Otwórz interfejs WWW (rysunek 3). Interfejs sieciowy ESPHome jest teraz dostępny po kliknięciu ESPHome Builder na lewym pasku bocznym Home Assistant.

Rysunek 3: Zainstaluj dodatek ESPHome Device Builder w Home Assistant.

Tworzenie konfiguracji płytki

Kliknij New Device w prawym dolnym rogu interfejsu internetowego ESPHome, aby utworzyć nową konfigurację urządzenia. Najpierw zostaniesz poinstruowany, jak zainstalować oprogramowanie układowe ESPHome na płycie. Kliknij Kontynuuj. Nazwij swoją konfigurację i wprowadź nazwę sieci Wi-Fi oraz hasło. Nawet w przypadku ESP32-H2 bez Wi-Fi należy wprowadzić sieć Wi-Fi, ponieważ ESPHome Web Builder nie został jeszcze dostosowany do tego przypadku.

W następnym kroku wybierz typ urządzenia. ESP32-C6 znajduje się na liście, ale w chwili pisania tego tekstu ESP32-H2 nie jest. Wybierz zatem pierwszą opcję. W obu przypadkach kliknij Skip, a następnie kliknij Edit na utworzonej konfiguracji. Zobaczysz teraz kod YAML konfiguracji ESPHome swojego urządzenia. Jeśli używasz ESP32-H2, zmień typ board z esp32-c6-devkitc-1 na esp32-h2-devkitm-1 i usuń całą sekcję wifi (w tym ssid i password, a także ap z jego ssid i password) i captive_portal, ponieważ ESP32-H2 nie ma Wi-Fi. W przypadku ESP32-C6 można pozostawić wszystkie ustawienia bez zmian. Kliknij Zapisz.

Konfiguracja Thread

Twoje urządzenie ESPHome obecnie nie ma sieci, co jest wskazywane przez czerwone bazgroły pod niektórymi elementami konfiguracji. Należy dodać urządzenie do sieci Thread. Najpierw wróć do Ustawienia | Urządzenia i usługi i kliknij Thread, ikonę koła zębatego i ikonę informacji obok preferowanej sieci. Za Active dataset TLVs, zobaczysz długi ciąg znaków szesnastkowych. Skopiuj ten ciąg i upewnij się, że zawiera wszystkie znaki. Następnie wróć do ESPHome Builder na lewym pasku bocznym Home Assistant i kliknij Edit na urządzeniu ESPHome. Dodaj następujący kod YAML w miejscu wifi:

Zastąp LONG_TLV długim ciągiem znaków szesnastkowych. Kodują one ustawienia sieciowe, takie jak kanał, nazwa sieci i klucz szyfrowania, umożliwiając urządzeniu dołączenie do sieci Thread. Kliknij Zapisz, a następnie Zainstaluj. Teraz podłącz płytkę ESP32 do komputera z uruchomionym programem Home Assistant. Jeśli jest to trudne, na przykład gdy Home Assistant działa na Raspberry Pi w piwnicy lub na strychu, zapoznaj się z polem "Ręczna instalacja oprogramowania układowego".

Rysunek 4: Za pomocą ESPHome Web można ręcznie zainstalować plik oprogramowania układowego.

Jak tylko płytka ESP32 zostanie podłączona do komputera z Home Assistant, wybierz Plug into the computer running ESPHome Device Builder na oferowanej liście opcji instalacji. Wybierz port szeregowy. W przypadku zestawu ESP32-H2-DEV-KIT-N4 dostępne będą dwa porty, opisane jako USB JTAG/serial debug unit i USB Single Serial: wybierz pierwszą opcję.

ESPHome tłumaczy teraz kod YAML urządzenia na C++ i kompiluje go do obrazu oprogramowania układowego. Może to zająć trochę czasu, zwłaszcza jeśli jest to pierwsze urządzenie ESPHome, ponieważ konstruktor musi następnie pobrać i zainstalować wszystkie niezbędne frameworki i biblioteki oprogramowania. Sama kompilacja oprogramowania układowego również zajmuje trochę czasu za pierwszym razem. Jeśli wszystko pójdzie dobrze, ostatecznie zobaczysz kilka zielonych komunikatów: INFO Successfully compiled program (pomyślnie skompilowano program), następnie INFO Successfully uploaded program (pomyślnie przesłano program), a na końcu INFO Starting log output from /dev/ttyACM0 with baud rate 115200 (uruchamianie wyjścia dziennika z /dev/ttyACM0 z szybkością transmisji 115200). Kliknij Stop, aby przerwać wyjście dziennika i zamknąć okno edycji z kodem YAML.

Integracja z ESPHome

Urządzenie ESPHome powinno być teraz wyświetlane jako ONLINE w ESPHome Builder, wskazując, że połączenie z Home Assistant przy użyciu interfejsu API Home Assistant przez sieć Thread działa. Od teraz można również bezprzewodowo aktualizować oprogramowanie sprzętowe urządzenia za pośrednictwem sieci Thread, co ze względu na niską przepustowość może zająć kilka minut. Aby to zrobić, wybierz Bezprzewodowo w Instaluj. Możesz także przeglądać logi bezprzewodowo (rysunek 5), więc płyta nie musi już być podłączona przez USB do komputera Home Assistant.

Aby użyć urządzenia Thread w Home Assistant, przejdź do Ustawienia | Urządzenia i usługi. W zakładce Integracje urządzenie ESPHome powinno pojawić się pod nagłówkiem Odkryte. Kliknij Add i potwierdź przyciskiem Submit, opcjonalnie przypisując pomieszczenie do urządzenia, i kliknij Finish. Jeśli wszystko pójdzie dobrze, możesz teraz wyświetlić informacje o urządzeniu, takie jak wersja oprogramowania układowego i adres MAC. Na razie urządzenie ma tylko jedną jednostkę do aktualizacji oprogramowania układowego, która jest domyślnie wyłączona. Ale teraz możesz dalej konfigurować płytkę za pomocą ESPHome, a dla każdej nowej funkcji dodatkowe encje pojawią się automatycznie w Home Assistant.

Rysunek 5: Dostęp do logów urządzenia ESPHome przez sieć Thread.

Sterowanie diodą LED

Płytka ESP32 jest teraz gotowa do dalszej konfiguracji w ESPHome. Kliknij Edit w ESPHome Builder pod nazwą urządzenia, aby dodać kod. Będziesz potrzebował dokumentacji dla konkretnej płytki, aby dowiedzieć się, jakie komponenty posiada i do których pinów są podłączone. Należy pamiętać, że zielona dioda LED na Super Mini ESP32-H2 miga stale, gdy bateria nie jest podłączona, co jest irytujące i nie można jej regulować za pomocą oprogramowania.

Po przeciwnej stronie złącza USB-C płytka ma niebieską diodę LED, którą można sterować za pomocą kodu przy użyciu pinu GPIO13. Aby uzyskać tę możliwość, należy dodać wyjście dla pinu 13 w konfiguracji ESPHome, wraz ze światłem odnoszącym się do tego wyjścia, jak pokazano na Listingu 1. Waveshare ESP32-H2-DEV-KIT-N4 nie ma kontrolowanej diody LED, ale można ją podłączyć do pinu GPIO z szeregowym rezystorem ograniczającym prąd o wartości 220 omów, a następnie użyć tego samego kodu ESPHome z odpowiednio zmienionym numerem pinu.

Zapisz tę konfigurację i zainstaluj ją na płytce ESP32, klikając Install w prawym górnym rogu, a następnie Wirelessly. Kod zostanie skompilowany i wysłany do ESP32 jako aktualizacja OTA przez sieć Thread.

Po zainstalowaniu nowego oprogramowania układowego na ESP32 Home Assistant rozpoznaje diodę LED. Kliknij na Urządzenia i usługi w ustawieniach, następnie na ESPHome w skonfigurowanych integracjach, a następnie na swoje urządzenie. Zobaczysz teraz swoją niebieską diodę LED w sekcji Controls (rysunek 6), którą możesz włączać i wyłączać, a niebieska dioda LED płyty natychmiast zareaguje.

Rysunek 6: Sterowanie diodą LED na płytce ESP32-H2 z Home Assistant przez sieć Thread.

Sterowanie diodą LED RGB

Płytka Super Mini ESP32-H2 posiada diodę LED RGB WS2812 pomiędzy przyciskami BOOT i RESET, podłączoną do GPIO8. Waveshare ESP32-H2-DEV-KIT-N4 również ma taką diodę LED RGB (w wariancie WS2812B) umieszczoną między złączem USB-C a przyciskiem RESET, podłączoną do tego samego GPIO. Można je skonfigurować w ESPHome podobnie jak w przypadku niebieskiej diody LED. Wymaga to kodu z Listingu 2.

Dla Waveshare ESP32-H2-DEV-KIT-N4 zmień rgb_order na RGB. Jeśli zachowujesz również konfigurację dla niebieskiej diody LED, upewnij się, że nie definiujesz light dwukrotnie, ale umieszczasz obie diody LED pod jednym kluczem light w pliku YAML. Zauważ, że powszechnie używana platforma neopixelbus nie działa tutaj, ponieważ implementacja OpenThread ESPHome obecnie opiera się tylko na ESP-IDF, a nie na frameworku Arduino, a NeoPixelBus jest dostępny tylko dla tego ostatniego.

Zapisz zmiany i zaktualizuj oprogramowanie układowe płytki. Gdy to zrobisz, Twoje urządzenie w Home Assistant będzie również zawierało encję dla diody LED RGB, w której możesz ustawić wyświetlanie wszystkich możliwych kolorów (rysunek 7).

Rysunek 7: Wbudowaną diodę LED RGB na płytce ESP32-H2 można również łatwo ustawić z poziomu Home Assistant.

Podłączanie przycisku

Ponieważ obsługa OpenThread w ESPHome jest wciąż nowa, specyficzne komponenty działające na zwykłych ESP32 mogą powodować problemy. Jednak technologia ta jest już całkiem użyteczna. Na przykład można podłączyć przycisk i poinformować Home Assistant poprzez sieć Thread, czy jest on włączony, czy wyłączony. Pokażę, jak to zrobić za pomocą zestawu Waveshare ESP32-H2-DEV-KIT-N4.

Umieść płytkę rozwojową na płytce prototypowej. Jeśli spojrzysz na pinout ESP32-H2-DEV-KIT-N4 w wiki Waveshare [16], znajdziesz pozycje GND, 3V3 i GPIO. Podłącz GND do niebieskiej szyny (-) płytki prototypowej, a 3V3 do czerwonej szyny (+). Umieść przycisk w środkowym rowku płytki prototypowej z nóżkami po obu stronach. Podłącz jedną nóżkę do szyny GND, a drugą przez rezystor podciągający 10 kOhm do szyny 3,3 V. Na koniec podłącz GPIO4 do nogi przycisku, która jest podłączona do rezystora (rysunek 8).

Rysunek 8: Waveshare ESP32-H2-DEV-KIT-N4 z przyciskiem i rezystorem podciągającym na płytce drukowanej.

Konfiguracja przycisku w ESPHome

Teraz, gdy sprzęt jest gotowy, dodaj kod z Listingu 3 do konfiguracji ESPHome dla płytki. Filtr jest używany do debouncingu: styki przycisków mogą otwierać się i zamykać wiele razy szybko po naciśnięciu lub zwolnieniu, zanim pozostaną w stabilnej pozycji. Aby uniknąć wielokrotnego włączania i wyłączania sygnałów, skonfigurowałem ESPHome tak, aby przekazywał stan tylko wtedy, gdy przycisk pozostaje wciśnięty przez ponad 20 ms.

Zauważ również, że pin jest skonfigurowany jako odwrócony. Gdy przycisk nie jest naciśnięty, nie ma połączenia między jego lewą i prawą nogą. W takiej sytuacji GPIO4 jest podłączone przez rezystor do 3,3 V. Po naciśnięciu przycisku GPIO4 łączy się z GND. Domyślnie ESPHome traktuje 3,3 V jako włączone, a GND jako wyłączone, a dodatek inverted: true odwraca to zachowanie.

Zapisz konfigurację i zainstaluj zaktualizowane oprogramowanie sprzętowe. Następnie w aplikacji Home Assistant pojawi się stan przycisku. Odpowiedzi przez sieć Thread po naciśnięciu lub zwolnieniu przycisku są natychmiastowe.

Dodawanie czujnika ruchu

W podobny sposób można podłączyć czujnik ruchu, na przykład pasywny czujnik podczerwieni (PIR). Zademonstruję to na przykładzie układu AM312, który ma trzy piny: VIN podłączony do szyny 3,3 V płytki prototypowej, GND do GND i OUT do GPIO4 układu ESP32 (rysunek 9). Czujnik PIR mierzy światło podczerwone emitowane przez obiekty (takie jak ludzie). Gdy następuje nagła zmiana, czujnik podaje napięcie 3,3 V na swój pin wyjściowy. Odczyt tego napięcia na pinie GPIO4 urządzenia ESP32 umożliwia wykrywanie ruchu.

Rysunek 9: Jeśli czujnik PIR AM312 wykryje ruch, podaje napięcie 3,3 V na swój pin OUT.

Konfiguracja ESPHome (Listing 4) jest prawie identyczna jak w przypadku przycisku. Filtr nie jest tutaj potrzebny, ponieważ płytka czujnika ma już wbudowane opóźnienie. Niektóre czujniki PIR umożliwiają regulację tego opóźnienia lub czułości za pomocą potencjometru. Za pomocą device_class: motion informujesz Home Assistant, że jest to czujnik ruchu, więc wyświetla on stan czujnika z ikoną idącej osoby na desce rozdzielczej. Po zapisaniu konfiguracji i zainstalowaniu oprogramowania układowego płytka ESP32-H2 będzie wysyłać powiadomienia do Home Assistant za pośrednictwem sieci Thread za każdym razem, gdy wykryje ruch.

Podsumowanie

Dzięki niedawnemu wsparciu ESPHome dla OpenThread możesz teraz tworzyć własne urządzenia Thread dla swojego inteligentnego domu bez wcześniejszego doświadczenia w programowaniu dla urządzeń wbudowanych. (Informacje na temat konfigurowania sieci mesh można znaleźć w sekcji "Tworzenie niezawodnej sieci mesh"). Integracja z Home Assistant działa bezbłędnie, ale byłoby interesujące, gdyby istniała inna metoda niż API Home Assistanta do komunikacji z urządzeniami. Należy również pamiętać, że obsługa OpenThread w ESPHome jest nadal eksperymentalna. Na przykład czujnik I2C (czujnik temperatury/ciśnienia/wilgotności BME280 [17]) nie działał podczas mojego początkowego testu z ESPHome 2025.6, ale kiedy ponownie spróbowałem dwa miesiące później, okazało się, że problem został naprawiony w ESPHome 2025.8. Inne problemy prawdopodobnie również zostaną rozwiązane w miarę upływu czasu.

Rysunek 10: Sieć Thread mesh składa się z wielu routerów (sześciokątów) łączących ze sobą urządzenia końcowe (okręgi).

Info

[1] Arduino: https://www.arduino.cc

[2] MicroPython: https://micropython.org

[3] ESPHome: https://esphome.io

[4] Koen Vervloesem, Tworzenie urządzeń automatyki domowej za pomocą ESPHome, "Linux Magazine" 12/2023, https://www.linuxpromagazine.com/Issues/2023/276/ESPHome

[5] Koen Vervloesem¸Getting Started with ESPHome, Elektor International Media B.V., 2021, https://www.elektor.com/products/getting-started-with-esphome

[6] Home Assistant: https://www.home-assistant.io

[7] Thread: https://www.threadgroup.org/What-is-Thread/Overview

[8] Koen Vervloesem, Building Wireless Sensor Networks with OpenThread, Elektor International Media B.V., 2024, https://www.elektor.com/products/building-wireless-sensor-networks-with-openthread

[9] Instrukcje instalacji Home Assistant: https://www.home-assistant.io/installation/ 

[10] Projekt OpenThread Border Router: https://github.com/openthread/ot-br-posix

[11] Projekt Espressif Thread Border Router: https://github.com/espressif/esp-thread-br

[12] Home Assistant Connect ZBT-1: https://www.home-assistant.io/connectzbt1/

[13] Wpływ zakłóceń radiowych USB 3.0 na urządzenia bezprzewodowe 2,4 GHz: https://www.usb.org/sites/default/files/327216.pdf

[14] ESPHome Device Builder: https://github.com/esphome/home-assistant-addon

[15] ESPHome Web: https://web.esphome.io

[16] Układ pinów ESP32-H2-DEV-KIT-N4: https://www.waveshare.com/wiki/ESP32-H2-DEV-KIT-N4#Pinout_Definition

[17] Czujnik temperatury/ciśnienia/wilgotności BME280: https://esphome.io/components/sensor/bme280/