Pierwsza automatyzacja w Home Assistant: otwarcie drzwi zapala światło

Masz Home Assistant świeżo po instalacji, pusty ekran i pomysł: "chcę, żeby po otwarciu drzwi zapaliło się światło". To najlepsza pierwsza automatyzacja: krótka, efekt widać od razu, a po drodze poznajesz pojęcia potrzebne później. Idziemy przez jeden udokumentowany zestaw sprzętu i jedną drogę konfiguracji.

Dla kogo jest ten poradnik i czego nie znajdziesz

Piszemy dla osoby, która ma już działający Home Assistant (dalej: HA) albo dopiero kupuje sprzęt i nigdy nie tworzyła automatyzacji. Zakładamy zerową wiedzę o Zigbee.

I od razu jasna deklaracja: nie ma tu żadnych prac przy instalacji elektrycznej. Nie montujemy przekaźników w puszkach, nie rozbieramy opraw, nie zdejmujemy osprzętu i nie dotykamy odsłoniętych przewodów ani stałej instalacji. Wszystko opiera się na urządzeniach, które wkłada się do gotowego gniazdka albo przykleja do futryny. Jakąkolwiek ingerencję w instalację 230 V zostaw osobie z odpowiednimi kwalifikacjami do prac elektrycznych.

Jargon w trzech zdaniach

Zigbee to bezprzewodowy standard małej mocy w paśmie 2,4 GHz - tym samym, w którym działa Wi-Fi. Koordynator zarządza siecią Zigbee; u nas jest to adapter USB wpięty do komputera z HA. Integracja to moduł HA rozmawiający z danym typem sprzętu - tutaj ZHA (Zigbee Home Automation). Encja (entity) to pojedyncza informacja lub przełącznik urządzenia: "drzwi otwarte/zamknięte" to jedna encja, "poziom baterii" druga.

Wybrany zestaw i dlaczego akurat taki

Trzymamy się jednego, konkretnego zestawu: Home Assistant Green (z fabrycznym Home Assistant OS) + Home Assistant Connect ZBT-2 jako koordynator na USB + integracja ZHA + czujnik otwarcia SONOFF SNZB-04P + wtyczka sterująca SONOFF iPlug S60ZBTPF z lampą stołową. Inne modele bywają zgodne, ale nie opisujemy ich tutaj i nie obiecujemy, że zadziałają identycznie.

Dlaczego Home Assistant OS? Bo to wariant wskazywany dziś przez oficjalną stronę instalacji, a w Green jest już zainstalowany. Metody Core i Supervised zespół HA zdeprecjonował 22 maja 2025 r.: powiadomienia od wydania 2025.6, utrata wsparcia z 2025.12. Starszy poradnik prowadzący przez "Supervised na Debianie" nie jest więc drogą, którą warto zaczynać.

Dlaczego Zigbee, a nie Wi-Fi? Bo urządzenia zigbee'owe rozmawiają lokalnie z koordynatorem, bez chmury producenta - automatyzacja "drzwi -> światło" ma wtedy działać także przy padniętym łączu.

Uwaga, która oszczędza rozczarowania: Home Assistant Green nie ma wbudowanego radia Zigbee. Potwierdza to baza wiedzy Nabu Casa i dokumentacja ZHA - żeby używać ZHA, trzeba dołożyć adapter. Green to komputer z preinstalowanym systemem, nie hub radiowy.

Który adapter? Bierzemy Home Assistant Connect ZBT-2, bo dokumentacja ZHA wskazuje go jako rekomendowany przy zakładaniu nowej sieci. Szczegół wart uwagi: ZBT-2 dedykujesz do Zigbee albo do Thread, nie do obu naraz - my wybieramy Zigbee. To urządzenie do użytku wewnątrz, zasilane z USB-C.

Czujnik drzwi. SONOFF SNZB-04P: Zigbee 3.0 (IEEE 802.15.4), bateria CR2477 3 V, czas parowania 180 s, deklarowany zasięg wewnątrz 30 m, szczelina między czujnikiem a magnesem przy zamkniętych drzwiach do 20 mm, zastosowanie wyłącznie wewnętrzne. Zmierz futrynę, zanim kupisz.

Sterowanie światłem bez dotykania instalacji. Zigbee'owa wtyczka w gotowym gniazdku, a w niej lampa stołowa. SONOFF iPlug S60ZBTPF: Zigbee 3.0, wejście 250 V~ 50/60 Hz maks. 16 A, obciążenie do 4000 W, praca wyłącznie wewnątrz, temperatura -10 do 40 stopni C. Instrukcja stawia też jeden konkretny warunek instalacyjny: obwód gniazdka ma być zabezpieczony wyłącznikiem nadprądowym (MCB) albo różnicowoprądowym z członem nadprądowym (RCBO) o prądzie znamionowym 16 A. Jeśli nie wiesz, jakie zabezpieczenie ma twój obwód, sprawdź opis w rozdzielnicy albo zapytaj elektryka - nie zgaduj.

Zasilana z sieci wtyczka pełni też rolę routera - według dokumentacji ZHA urządzenia zasilane z sieci przekazują pakiety dalej, poprawiając zasięg. Czujnik na baterii to urządzenie końcowe (end device), które niczego nie przekazuje. To rozróżnienie wyznacza kolejność w dalszej części poradnika.

Lampa też ma warunek: zwykła, z mechanicznym włącznikiem, który zostawisz w pozycji "włączone" - wtedy jej stanem rządzi wyłącznie wtyczka. Lampa dotykowa albo ściemniana pilotem po odcięciu zasilania nie musi wrócić do świecenia.

Zanim zaczniesz - lista wymagań

Działający Home Assistant OS z aktualizacjami i wolny port USB 2.0. To nie jest preferencja: dokumentacja ZHA w sekcji o ograniczaniu zakłóceń zaleca podłączanie adaptera Zigbee do portu USB 2.0, a nie USB 3.x, a przy komputerze mającym wyłącznie porty USB 3.x - użycie zasilanego huba USB 2.0; osobno wskazuje, by trzymać adapter z dala od urządzeń i kabli USB 3.x - ZHA.
Przedłużacz USB do adaptera Zigbee - jest w pudełku z ZBT-2 i nie jest ozdobą. Nabu Casa ostrzega, że porty i dyski USB 3.0 potrafią zakłócać protokoły w paśmie 2,4 GHz, w tym Zigbee. Przedłużacz odsuwa antenę od źródła zakłóceń.
Nowe, własne urządzenia Zigbee - takie, których jeszcze nigdzie nie sparowałeś.
Bateria CR2477 w czujniku i około 30 minut spokoju.
Sprawne gniazdko i zwykła lampa - szczegóły sprawdzasz przed wpięciem wtyczki w kroku 3.

Krok 1: kopia zapasowa, zanim cokolwiek zmienisz

Zrób to nawet przy pustej instalacji. Wejdź w Ustawienia > System > Kopie zapasowe (Settings > System > Backups) i uruchom Set up backups. Dokumentacja HA podkreśla dwie rzeczy:

Pobierz emergency kit (zestaw awaryjny) i schowaj go bezpiecznie - bez klucza szyfrowania nie odtworzysz zaszyfrowanej kopii.
Trzymaj kopię poza samym urządzeniem. Backupy na dysku, który właśnie padł, to nie backupy.

A sama sieć Zigbee? ZHA wykonuje automatyczne kopie sieci Zigbee, pozwala je odtworzyć albo przenieść sieć na inny koordynator; kopię ręczną zrobisz w Network Settings. Dokumentacja mówi wprost, że po przywróceniu kopii HA można zrekonfigurować ZHA lub zmigrować na nowy koordynator bez utraty ustawień i podłączonych urządzeń. Są jednak warunki: poprzedni adapter musi pracować w ZHA (nie w deCONZ czy Zigbee2MQTT), radio musi być typu ezsp, znp lub deCONZ, a kopia musi pochodzić z wnętrza ZHA. Bez przeniesienia adresu IEEE ze starego adaptera część urządzeń trzeba będzie podłączyć ponownie, a po migracji sprzęt wraca do sieci zwykle w ciągu godziny. Backup jest więc realnym zabezpieczeniem - w udokumentowanych granicach, nie jako gwarancja.

Krok 2: podłącz adapter Zigbee

Kolejność kroków bierzemy z instrukcji Nabu Casa dla zakładania nowej sieci Zigbee z Connect ZBT-2.

Wybierz miejsce. Z dala od grubych ścian, metalu, siatki zbrojeniowej, innych nadajników (komputery, routery, porty USB 3.0, dyski SSD) i akwarium.
Złóż adapter. Przykręć antenę do podstawy - bez siły - i ustaw ją pionowo. Nie mocuj niczego na stałe; po testach możesz chcieć adapter przestawić.
Podłącz. Adapter w przedłużacz USB, przedłużacz w port USB komputera z HA.
Ustawienia > Urządzenia i usługi (Settings > Devices & services). ZBT-2 powinien zostać wykryty. Wybierz Add.
W oknie wyboru protokołu wybierz Use as Zigbee adapter.
Przy typie instalacji wybierz Recommended installation - to konfiguruje ZHA. Custom jest dla osób z własnym kontrolerem (np. Zigbee2MQTT) i nie jest opisany w tej dokumentacji.
Przejdź przez ekrany do końca, przypisz adapter do obszaru i wybierz Finish.

Jeśli adapter nie został wykryty, dodaj ZHA ręcznie: Add Integration > Zigbee Home Automation i wskaż ścieżkę urządzenia szeregowego - dokumentacja ZHA zaleca tę z katalogu /dev/serial/by-id, bo nie zmienia się po przepięciu portu. Listę znajdziesz w Ustawienia > System > Sprzęt (Settings > System > Hardware), pod All Hardware.

Oczekiwany rezultat: integracja Zigbee Home Automation jest skonfigurowana, a sieć Zigbee utworzona.

Krok 3: sparuj wtyczkę i podłącz lampę

Dlaczego wtyczka jest pierwsza. Dokumentacja ZHA w dobrych praktykach parowania zaleca, by zaczynać od urządzeń zasilanych z sieci, zanim doda się urządzenia bateryjne, i osobno ostrzega, że "słaba" sieć Zigbee może uniemożliwić sparowanie części urządzeń - ZHA, best practices. Wtyczka zasilana z sieci jest routerem i wzmacnia świeżo utworzoną sieć; czujnik na baterii jest urządzeniem końcowym i w słabej sieci potrafi się sparować, a potem zniknąć. Dlatego najpierw wtyczka, dopiero potem czujnik.

Zanim cokolwiek wepniesz sprawdź: gniazdko (sprawne, bez luzu, na obwodzie z zabezpieczeniem MCB lub RCBO 16 A), lampę (zwykła, z mechanicznym włącznikiem, sprawna żarówka) i obciążenie - lampa LED to kilka watów przy limicie 4000 W wtyczki. Dopiero potem wkładaj wtyczkę do gniazdka, a włącznik lampy zostaw w pozycji "włączone" i już go nie ruszaj.

Uwaga przed przytrzymaniem przycisku: w S60ZBTPF przytrzymanie przycisku przez 5 sekund to jednocześnie wejście w tryb parowania i przywrócenie ustawień fabrycznych - tak opisuje to instrukcja producenta ("Press and hold the device button for 5 seconds to restore factory settings"). Na wtyczce, która już gdzieś pracuje, odetnie to jej dotychczasową konfigurację. Zakładamy tu urządzenia nowe, jeszcze nigdzie nie sparowane.

Wejdź w Ustawienia > Urządzenia i usługi (Settings > Devices & services), wybierz integrację Zigbee Home Automation i Add device. ZHA zacznie szukać urządzeń w trybie parowania. (W części wydań ta sama lista jest też dostępna jako Ustawienia > Zigbee.)
Wtyczka ma już być w docelowym gniazdku - nie paruj jej obok koordynatora, bo sprawdzisz zasięg w warunkach, których potem nie będzie. Przytrzymaj przycisk przez 5 sekund, aż niebieska dioda zacznie migać wolno; miga tak przez okno parowania trwające 180 sekund. Stałe świecenie oznacza nawiązane połączenie z koordynatorem.
Urządzenie pojawi się na liście - nazwij je (np. "Lampa w przedpokoju") i przypisz do obszaru.
Sprawdź, czy przełącznik w HA zapala i gasi lampę. To jest oczekiwany rezultat tego kroku.

Przy innych odbiornikach - zwłaszcza grzejnych i z silnikiem (wyższy prąd rozruchowy) - stosuj się do instrukcji konkretnego modelu. Nie zakładaj, że dowolna wtyczka je udźwignie, i nie traktuj deklarowanych zabezpieczeń jako gwarancji bezpieczeństwa.

Krok 4: sparuj czujnik drzwi

Sieć ma już router, więc czujnik ma się do czego przyłączyć.

Uwaga przed przytrzymaniem przycisku: w SNZB-04P te dwie rzeczy to dwa różne czasy, których nie wolno mylić. Instrukcja SONOFF podaje w tabeli przycisku: przytrzymanie 5 sekund - "Device enters the pairing mode", czyli samo wejście w tryb parowania. Twardy reset to osobne przytrzymanie przez 10 sekund, opisane dopiero w sekcji rozwiązywania problemów ("reset the sensor (press and hold the button for 10 seconds) and try again"). Producent nie pisze, że samo 5-sekundowe wejście w parowanie kasuje powiązanie z poprzednią bramką - dlatego po prostu używaj urządzeń nowych, jeszcze nigdzie nie sparowanych.

W integracji Zigbee Home Automation ponownie wybierz Add device.
Wprowadź czujnik w tryb parowania: SONOFF opisuje wyjęcie paska izolującego baterię (pierwsze uruchomienie samo wchodzi w parowanie) albo przytrzymanie przycisku przez 5 sekund, aż zamiga dioda. Czerwona dioda miga wolno przez 180 sekund - to okno parowania; po udanym połączeniu świeci 3 sekundy i gaśnie.
Paruj czujnik przy drzwiach, w miejscu docelowym. Dokumentacja ZHA mówi wprost: "Try to pair Zigbee devices where you intend to use them: Avoid pairing next to the Zigbee coordinator if you intend to move its location afterward", bo przeniesienie po sparowaniu potrafi pogorszyć połączenie.
Poczekaj. Urządzenie pojawi się na liście, nazwij je (np. "Drzwi wejściowe") i przypisz do obszaru.
Wejdź w urządzenie i sprawdź encje. Powinieneś zobaczyć encję typu binary_sensor ze stanem otwarty/zamknięty oraz encję baterii.

Test bez automatyzacji: otwórz i zamknij drzwi, patrząc na stan encji w HA. Zmiana w ciągu sekundy to dobry wynik.

Jeśli nie działa:

Czujnik w ogóle się nie znajduje: sprawdź pasek izolujący baterię i spróbuj ponownie. ZHA sugeruje kilkukrotne powtórzenie parowania, SONOFF - przybliżenie czujnika do bramki. Traktuj to jako doraźną diagnostykę: po sparowaniu z bliska i tak musisz sprawdzić, czy czujnik działa z miejsca docelowego.
Nadal nie wchodzi w parowanie: dopiero teraz twardy reset - przytrzymanie przycisku przez 10 sekund - i próba od nowa.
Czujnik paruje się, ale potem znika: ZHA ma parametr "Consider battery-powered devices unavailable after" z domyślną wartością 21600 sekund - czujniki bateryjne odzywają się rzadko i to normalne. Druga częsta przyczyna to za duża odległość od koordynatora i najbliższego routera.
Podejrzewasz zakłócenia: według ZHA przy kolizji z Wi-Fi lepiej ustawić stały kanał Wi-Fi na routerze, niż zmieniać kanał Zigbee.

Krok 5: zbuduj automatyzację

Automatyzacja w HA to wyzwalacz, opcjonalny warunek i akcja. Nasza brzmi: gdy drzwi się otworzą, i jest ciemno, włącz lampę. Etykiety podajemy po polsku, w nawiasie angielskie - zobaczysz jedne albo drugie, zależnie od języka interfejsu.

Wejdź w Ustawienia > Automatyzacje i sceny (Settings > Automations & scenes).
W prawym dolnym rogu wybierz Utwórz automatyzację > Utwórz nową automatyzację (Create automation > Create new automation).
W sekcji Kiedy (When) wybierz Dodaj wyzwalacz (Add trigger), wpisz nazwę czujnika ("Drzwi wejściowe"), wskaż jego encję binary_sensor i ustaw zmianę stanu na Otwarte (Open).
W sekcji Oraz jeśli (And if) wybierz Dodaj warunek (Add condition), potem Encja > Stan (Entity > State). W polu encji wpisz sun.sun, jako stan wybierz below_horizon. Encję daje wbudowana integracja Sun, a jej dokumentacja podaje tylko dwa stany: above_horizon i below_horizon. Dlatego ten jeden warunek obejmuje całą noc - również po północy.
W sekcji Następnie zrób (Then do) wybierz Dodaj akcję (Add action), wskaż encję przełącznika wtyczki i akcję włączenia (Switch: Turn on).
Zapisz (Save) i nadaj nazwę, np. "Drzwi wejściowe - światło po zmroku".

Dlaczego sun.sun, a nie warunek słońca z kluczem after: sunset? Bo tam czai się pułapka: dokumentacja warunków mówi wprost, że sam after daje okres od zachodu do północy, a sam before - od północy do wschodu. Warunek "po zachodzie" o drugiej w nocy jest już fałszywy. Poprawne alternatywy to oba klucze naraz (after: sunset i before: sunrise) albo prosty stan below_horizon, który wybraliśmy.

Oczekiwany rezultat: otwarcie drzwi po zmroku zapala lampę - o każdej porze nocy.

Jak sprawdzić części składowe za dnia:

Akcja: w menu trzech kropek automatyzacji wybierz Uruchom akcje (Run actions). Dokumentacja testowania automatyzacji mówi jasno, że ta opcja wykonuje wszystkie akcje, pomijając wyzwalacze i warunki. To test wyłącznie części wykonawczej - lampa zapali się także w południe, a o wyzwalaczu i warunku nie dowiesz się z niego nic.
Warunek: w menu trzech kropek wiersza warunku jest Testuj (Test) - pokaże, czy warunek jest w tej chwili spełniony. Stan sun.sun podejrzysz też w Narzędzia deweloperskie > Stany (Developer tools > States).
Całość: pełne przejście - wyzwalacz, warunek, akcja - sprawdzisz dopiero fizycznym otwarciem drzwi po zmroku; przebieg zobaczysz w Śladach (Traces).

Gaszenie świadomie pomijamy w pierwszym podejściu - to naturalny drugi krok, ale najpierw upewnij się, że "otwarcie -> zapalenie" działa powtarzalnie.

Bezpieczne wycofanie się

Każdy element da się cofnąć bez prac przy instalacji:

Automatyzacja: w Ustawienia > Automatyzacje i sceny najpierw wyłącz ją przełącznikiem, dopiero potem kasuj.
Urządzenie Zigbee: ZHA udostępnia akcję zha.remove, która usuwa węzeł z sieci.
Cała integracja: Ustawienia > Urządzenia i usługi, karta integracji, menu trzech kropek, Delete.
Sprzęt: adapter USB wypinasz, wtyczkę wyjmujesz z gniazdka, taśmę czujnika odklejasz. Nic nie jest wiercone ani lutowane, choć po klejach montażowych potrafi zostać ślad.

Czego ten poradnik nie obiecuje

Redakcja nie zbudowała tego zestawu na własnym stanowisku - kroki i parametry pochodzą z dokumentacji Home Assistant, Nabu Casa i SONOFF, nie z testu. Nie obiecujemy zgodności: SONOFF wymienia własne bramki i ogólnie kontrolery Zigbee 3.0 z zastrzeżeniem, że bywa to zależne od produktu. Kopia zapasowa też nie jest gwarancją - ZHA dokumentuje backup i migrację sieci, ale w opisanych granicach. Zigbee dzieli pasmo 2,4 GHz z Wi-Fi i portami USB 3.0, więc nie jest odporne na zakłócenia.

Nazwy przycisków i układ ekranów zmieniają się między wydaniami. Jeśli zobaczysz inną etykietę, szukaj kroku o tym samym znaczeniu.

Lista kontrolna na koniec

Instalacja to HA OS, nie zdeprecjonowane Core/Supervised.
Adapter ZBT-2 złożony (antena pionowo), wpięty przez przedłużacz USB do portu USB 2.0, z dala od urządzeń USB 3.0.
Backup skonfigurowany, emergency kit pobrany i schowany poza urządzeniem.
Gniazdko (zabezpieczenie MCB/RCBO 16 A), lampa i obciążenie sprawdzone przed wpięciem wtyczki; włącznik lampy w pozycji "włączone".
Wtyczka sparowana jako pierwsza, w docelowym gniazdku; lampa reaguje na przełącznik w HA.
Czujnik drzwi sparowany po wtyczce, przy drzwiach, i zgłasza zmianę stanu przy otwarciu i zamknięciu.
Warunek nocny to sun.sun = below_horizon (albo after: sunset z before: sunrise).
Automatyzacja zapisana, sprawdzona fizycznym otwarciem drzwi po zmroku (nie tylko przez Run actions), i wiesz, jak ją wyłączyć.

Gdy to działa, masz szkielet pod resztę: czujnik ruchu zamiast kontaktronu, syrena zamiast lampy, powiadomienie zamiast obu.

Źródła

Home Assistant - Installation - wspierane typy instalacji.
Home Assistant Community - Deprecating Core and Supervised installation methods - ogłoszenie z 22 maja 2025 r. i okno wsparcia do 2025.12.
Home Assistant - Zigbee Home Automation (ZHA) - koordynatory, brak radia w HA Green, routery i end devices, kanały, timeouty, zha.remove, backupy sieci Zigbee i warunki migracji.
Nabu Casa - Does Home Assistant Green have onboard radios? - potwierdzenie braku radiówek w HA Green.
Nabu Casa - Forming a new Zigbee network with Home Assistant Connect ZBT-2 - kroki kreatora ZBT-2, montaż anteny, zakłócenia USB 3.0.
Home Assistant Connect ZBT-2 - specyfikacja, Zigbee albo Thread.
Home Assistant - Understanding automations - budowa automatyzacji i edytor wizualny.
Home Assistant - Testing and troubleshooting automations - Run actions pomija wyzwalacze i warunki; testy pojedynczych bloków; ślady.
Home Assistant - Sun - encja sun.sun i jej dwa stany: above_horizon / below_horizon.
Home Assistant - Common tasks (Backups) - kopie zapasowe, emergency kit.
Home Assistant - Conditions - warunek słońca przy samym after/before.
SONOFF SNZB-04P - Zigbee 3.0, CR2477, parowanie 180 s, przytrzymanie przycisku 5 s = wejście w tryb parowania, osobny twardy reset 10 s, dystans montażowy do 20 mm.
SONOFF iPlug S60ZBTPF - Zigbee 3.0, 250 V~ maks. 16 A, 4000 W, parowanie 5 s i okno 180 s, to samo przytrzymanie 5 s przywraca ustawienia fabryczne, wymóg zabezpieczenia MCB lub RCBO 16 A przed wtyczką.