IKEA nie paruje się z Zigbee2MQTT: pełna diagnostyka resetu, interview i koordynatora
Masz żarówkę albo pilota IKEA, migają jak trzeba przy resecie, a mimo to w Zigbee2MQTT nic się nie dzieje; albo dzieje się coś gorszego: urządzenie na chwilę się pojawia, dostaje status „unsupported” i znika. Napisałem ten artykuł, bo to jedno z najczęstszych pytań, jakie dostaję po publikacji przewodnika o architekturze IKEA i Home Assistant, i bo odpowiedź „po prostu zresetuj jeszcze raz” w 80% przypadków niczego nie rozwiązuje.
Ten tekst jest długi celowo. Diagnostyka Zigbee to proces warstwowy: od fizycznego urządzenia, przez radiowy handshake, aż po to, czy Home Assistant w ogóle dostał wiadomość z MQTT. Jeśli pójdziesz na skróty i zaczniesz od najpopularniejszej porady z forum, prawdopodobieństwo trafienia w Twój konkretny przypadek jest niskie. Rozbijamy to warstwa po warstwie, z prawdziwymi przykładami zgłoszeń z GitHuba i community Home Assistant.
6
Scenariuszy niepowodzenia
6
Warstw diagnostyki
5
Typów błędów logu
Z2M 2.x
Discovery breaking change
Seria: IKEA Smart Home × Home Assistant
Co naprawdę oznacza „nie paruje się”
Zanim zaczniesz cokolwiek resetować, ustal precyzyjnie, na którym etapie utknąłeś: każdy z tych etapów ma inną przyczynę i inne rozwiązanie.
Zanim zaczniesz szukać winy w urządzeniu: przy zupełnym braku logu sprawdź kolejno: czy Zigbee2MQTT w ogóle wystartował bez błędów adaptera (log uruchomienia pokazuje typ adaptera, firmware, kanał i PAN ID); czy Permit join jest aktywne i czy jest aktywne globalnie, czy tylko przez wybrany router; czy poprzednia bramka IKEA albo inny hub Zigbee (Hue, deCONZ na innym porcie) nie jest nadal włączona; czy urządzenie faktycznie wykonało poprawny reset; czy to na pewno urządzenie Zigbee, a nie Matter/Thread; czy adapter przyjmuje jakiekolwiek inne nowe urządzenia; oraz, przy adapterach Texas Instruments, czy
coordinator_check nie wskazuje brakujących routerów. Osobny, rzadszy przypadek to dołączenie z adresem 0x0000000000000000 w logu interview: to sygnał możliwego uszkodzenia starszego adaptera z rodziny CC253x.Pełny przebieg dołączania urządzenia do sieci
Wszystko zaczyna się od resetu urządzenia do trybu parowania, ale to nie jest jeden, jednoznaczny proces. Factory reset (procedura producenta), leave request (komunikat wysłany do starego koordynatora informujący o opuszczeniu sieci) i force remove w Zigbee2MQTT (usunięcie rekordu z bazy po stronie oprogramowania) to trzy różne operacje. Force remove kasuje wpis w
database.db, ale nie gwarantuje, że samo urządzenie „zapomniało” starą sieć i klucz sieciowy: jeśli procedura resetu na urządzeniu nie zadziałała poprawnie, może ono nadal próbować wrócić do poprzedniego koordynatora zamiast dołączyć jako nowe.Następnie zachodzi network join: urządzenie wysyła żądanie dołączenia, koordynator lub router odpowiada, przydzielany jest krótki adres sieciowy. Na tym etapie Zigbee2MQTT loguje komunikat
Device joined.Kolejny krok to odczyt node descriptor: podstawowych informacji o typie urządzenia i jego możliwościach. Zaraz po nim następuje odpytanie o active endpoints, czyli listę logicznych „portów” w urządzeniu.
Dla każdego endpointu Zigbee2MQTT odczytuje listę klastrów: zestawów funkcji (np.
genOnOff, genLevelCtrl, lightingColorCtrl, closuresWindowCovering). Ten zestaw razem z modelID i manufacturerName tworzy fingerprint urządzenia, po którym Zigbee2MQTT dopasowuje je do konwertera w bazie: dla prostych urządzeń często wystarczy samo modelID, ale urządzenia współdzielące ten sam identyfikator między rewizjami wymagają dokładniejszego dopasowania po endpointach i klastrach.Jeśli fingerprint pasuje, następuje configure: ustawienie automatycznego raportowania zmian stanu (binding i reporting). To jednak osobny krok od MQTT Discovery, czyli publikacji opisu urządzenia do Home Assistant: reprezentacja urządzenia i encje mogą powstać zaraz po rozpoznaniu definicji, jeszcze zanim configure zdąży się w pełni zakończyć. W praktyce oznacza to, że urządzenie może pojawić się w Home Assistant, ale nie raportować stanów poprawnie, dopóki configure się nie domknie, a nie każde urządzenie w ogóle obsługuje standardowe configure reporting.
Każdy z tych kroków może zawieść osobno: to dlatego uniwersalna rada „zresetuj i spróbuj ponownie” działa tylko czasem.
Rozpoznanie protokołu, zanim zaczniesz diagnozować
Zanim zaczniesz szukać przyczyny w Zigbee2MQTT, upewnij się, że w ogóle próbujesz sparować urządzenie Zigbee, a nie Matter. To coraz częstsza pomyłka odkąd IKEA sprzedaje obok siebie produkty z dwóch różnych generacji, czasem o bardzo podobnych nazwach.
BILRESA i KAJPLATS: to natywne urządzenia Matter/Thread i domyślnie nie nadają się do dodania do Zigbee2MQTT w standardowy sposób. Dla części modeli KAJPLATS (np. LED2405G8) baza Zigbee2MQTT dokumentuje dodatkowo nieoficjalny, uproszczony tryb zgodności Zigbee, uruchamiany inną procedurą niż zwykły sześciokrotny reset: to nie jest ścieżka producenta, funkcje są ograniczone, aktualizacje firmware mogą ją w przyszłości usunąć, a same urządzenie nie dostaje przez ten tryb aktualizacji OTA. Zanim spróbujesz tej ścieżki dla konkretnego modelu, sprawdź jego stronę w bazie Zigbee2MQTT i traktuj to jako eksperyment, nie standardową procedurę.
Zasada praktyczna: sam kod QR na pudełku nie jest dowodem na Matter: Zigbee 3.0 również wykorzystuje kody QR i install code do bezpiecznego commissioning (obsługiwane m.in. przez adaptery zStack, ember i deCONZ z odpowiednim firmware). Sprawdzaj raczej logo Matter/Thread, dokładny numer modelu i wpis w bazie Zigbee2MQTT. Jeśli pudełko lub aplikacja IKEA jednoznacznie wskazuje na Matter lub Thread, nie próbuj dodawać urządzenia przez „Permit join” w Zigbee2MQTT: użyj kontrolera Matter w Home Assistant albo aplikacji IKEA Home Smart. Szczegóły w artykule o DIRIGERA, Matter i nowej generacji urządzeń.
Procedury resetu według typu urządzenia: ogólne zasady
Pełne procedury krok po kroku dla konkretnych modeli znajdziesz w artykułach o żarówkach, pilotach, czujnikach i roletach: poszczególne modele IKEA różnią się liczbą naciśnięć, długością przytrzymania i tym, czy w ogóle mają fizyczny przycisk resetu, dlatego traktuj poniższe zasady jako punkt startowy, a nie ostateczną instrukcję. Zanim zaczniesz, warto też sprawdzić stronę konkretnego modelu w bazie Zigbee2MQTT: często znajduje się tam dokładna procedura, informacja o konieczności wybudzania czy znane problemy firmware.
Urządzenia bateryjne: sen, wybudzanie i niepełne configure
Urządzenia bateryjne śpią większość czasu i budzą się tylko na krótkie okna. Jeśli interview albo configure nie zdąży się zakończyć w tym oknie, proces zawiśnie w połowie: stąd tak częste
Interview failed właśnie przy pilotach i czujnikach.Sprawdzona metoda: utrzymuj urządzenie „obudzone” w trakcie parowania: naciskaj przycisk co kilka sekund, dopóki proces się nie zakończy, zamiast zostawiać je samo sobie po jednorazowym resecie.
Bateria pod obciążeniem: może pokazywać akceptowalne napięcie w spoczynku, ale zapadać się pod chwilowym obciążeniem przy transmisji radiowej. Jeśli parowanie jest niewytłumaczalnie kapryśne, po prostu wymień baterię na nową.
Niepełne configure objawia się tak, że urządzenie jest widoczne, sparowane, ale nie publikuje
battery. Zanim od razu wymusisz Reconfigure, sprawdź, jak często dany model w ogóle raportuje poziom baterii: część czujników robi to co kilka-kilkanaście godzin albo dopiero po istotnej zmianie napięcia, więc pozorny brak danych bywa po prostu kwestią czasu, nie błędem configure. Reconfigure wykonuj zaraz po naciśnięciu przycisku (urządzenie musi być „obudzone”), ale nie traktuj go jako uniwersalnego lekarstwa na każdy brak wartości.Urządzenia sieciowe: inny zestaw problemów
Żarówki, gniazdka i sterowniki LED zasilane z sieci są zawsze aktywne: brak snu oznacza ciągłe nasłuchiwanie, a większość (choć nie wszystkie, dokumentacja Zigbee2MQTT mówi „almost all”, nie „wszystkie”, bo są np. wyjątki wśród modułów bez przewodu neutralnego) pełni też rolę routera przekazującego ruch dla innych urządzeń. Rzeczywistą rolę danego urządzenia najlepiej potwierdzić w mapie sieci, a nie zakładać automatycznie na podstawie samego faktu stałego zasilania. To zaleta dla mesh, ale też oznacza, że wadliwe czy przeciążone urządzenie odbije się na innych, pozornie niepowiązanych.
Niepełny reset: zdarza się, gdy włącznik ścienny przerywa cykl zbyt szybko/wolno. Nie wykręcaj żarówki z oprawki między cyklami pod napięciem: to niewygodne, ryzykowne dla gwintu i styków, i utrudnia utrzymanie równego rytmu. Zamiast tego użyj lampki z łatwo dostępnym przełącznikiem, oprawki testowej albo listwy/gniazdka z wyłącznikiem mechanicznym.
Zasilanie ma znaczenie dla stabilności: tania listwa z filtrem albo niekompatybilny ściemniacz potrafi wprowadzać zakłócenia wpływające na radiową część układu.
Firmware urządzeń sieciowych bywa aktualizowany częściej niż bateryjnych, co czasem prowadzi do sytuacji, w której dwa identyczne modele zachowują się różnie tylko dlatego, że są na różnych wersjach: kwestie OTA opisuję szerzej przy poszczególnych kategoriach urządzeń w dalszych częściach serii.
Interpretacja błędów: co naprawdę oznaczają logi
„Interview failed because can not get active endpoints”
Koordynator zdołał odczytać deskryptor węzła, ale nie doczekał się odpowiedzi na zapytanie o listę endpointów: najczęściej zbyt słaby sygnał albo zbyt krótkie okno aktywności urządzenia bateryjnego. W jednym z udokumentowanych przypadków na GitHubie problem dotyczył czujnika ruchu TRÅDFRI z aktywnym bindingiem do dwóch żarówek: po force-removal i wyjęciu/włożeniu baterii urządzenie połączyło się bez problemu, ale bindingi trzeba było odtworzyć ręcznie.
„Unsupported”
Warto rozdzielić dwa scenariusze. Pierwszy to interview, który w ogóle się nie kończy: Zigbee2MQTT nie ma wystarczających danych o urządzeniu. Drugi to interview zakończony sukcesem, ale ze statusem
supported: false: dane (modelID, manufacturerName, endpointy, klastry) są już zebrane, tylko żaden konwerter w bazie ich nie obsługuje. W drugim przypadku pomaga aktualizacja Zigbee2MQTT (konwerter mógł zostać dodany później), a w ostateczności napisanie external convertera na bazie zebranego fingerprintu. W zgłoszeniach dotyczących modelu LED2101G4 urządzenie parowało się poprawnie na poziomie sieci, ale interview nigdy nie kończył się sukcesem, przez co żarówka zostawała trwale oznaczona jako unsupported i wymagała wymuszonego usunięcia z bazy przed każdą kolejną próbą.ApsNoAck i MacNoAck
ApsNoAck to brak potwierdzenia na warstwie APS. To symptom, nie diagnoza: może oznaczać urządzenie offline, zerwaną trasę, słaby link w jedną stronę, przeciążenie sieci, śpiące urządzenie, zniknięcie rodzica albo błąd firmware, a nie tylko chwilowe przeciążenie łącza czy problem sterownika adaptera. MacNoAck to błąd niżej w stosie, bliżej warstwy radiowej: również nie zawsze oznacza wyłącznie fizyczny problem: to może być chwilowo wyłączone urządzenie, nieaktualna tabela sąsiadów czy zniknięcie routera, przez który urządzenie próbuje się połączyć. Oficjalna dokumentacja deCONZ osobno ostrzega, że ConBee II (i możliwe RaspBee II) bywają źródłem problemów z łącznością objawiających się właśnie MacNoAck: warto traktować to jako udokumentowany przypadek konkretnego adaptera, a nie definicję samego błędu. Oba błędy najlepiej korelować z mapą sieci, czasem ostatniej aktywności i typem urządzenia, zamiast oceniać w oderwaniu.„No network route” (kod 205)
Koordynator wie, że urządzenie istnieje, ale nie ma do niego aktualnie trasy: najczęściej router, przez który szedł ruch, zniknął z sieci, zmienił się fizycznie, albo brakuje route discovery. Ten błąd może wystąpić w każdej sieci Zigbee, niezależnie od koordynatora. Jeśli używasz adaptera Texas Instruments, warto najpierw wykonać
coordinator_check: funkcję wykrywającą routery brakujące w pamięci koordynatora (opisaną szerzej w sekcji o koordynatorach). Dopiero w drugiej kolejności warto wspomnieć, że stare koordynatory CC2531/CC2530 zwiększają ryzyko takich problemów w większych sieciach i Zigbee2MQTT wprost zaleca nowsze adaptery.„No response received”
Ogólny komunikat oznaczający brak odpowiedzi w oczekiwanym czasie, ale zanim zaczniesz od warstwy fizycznej, ustal, jakiej operacji dotyczył (configure, OTA, zwykłe sterowanie, odczyt atrybutu), do jakiego endpointu i klastra, oraz czy urządzenie jest bateryjne. Dopiero taka korelacja mówi, czy problemem jest zasięg, zasilanie, śpiące urządzenie, czy np. komenda niezgodna z firmware.
Koordynatory: to, od czego naprawdę wszystko zależy
Wybór i stan koordynatora to zmienna, którą najłatwiej pominąć, a która tłumaczy zaskakująco dużo przypadkowo wyglądających problemów.
Multiprotokół: dotyczy sytuacji, w której jedno radio obsługuje jednocześnie Zigbee i Thread. To nie jest po prostu kwestia „nienakładających się kanałów” jak przy dwóch osobnych dongle’ach: współdzielone radio musi dzielić czas antenowy między oba stosy, co zależy od konkretnej implementacji firmware i bywa źródłem niestabilności trudnej do zdiagnozowania. Jeśli masz oddzielny adapter Zigbee i niezależny Thread Border Router (np. w DIRIGERA), ten problem Cię nie dotyczy: dopiero jedno wspólne radio multiprotokołowe wymaga świadomej konfiguracji.
coordinator_check (adaptery TI): jeśli używasz adaptera Texas Instruments (CC2652/CC1352), a nowe urządzenia nie chcą dołączyć albo istniejące „odpadają” z sieci, wyślij pusty payload na
zigbee2mqtt/bridge/request/coordinator_check. Odpowiedź na .../response/coordinator_check zawiera listę routerów, o których pamięć koordynatora „zapomniała”: najczęściej po migracji ze starego koordynatora Zigbee 1.2 albo po aktualizacji firmware. Rozwiązaniem jest ponowne sparowanie tych konkretnych routerów.USB, Ethernet i zakłócenia: problem, który wygląda jak wszystko inne
To jeden z najbardziej niedocenianych tematów w całej diagnostyce Zigbee, a jednocześnie jeden z najlepiej udokumentowanych.
USB 3.0 i SSD: porty USB 3.0 emitują szumy radiowe blisko 2,4 GHz, tego samego pasma co Zigbee. Dokumentacja Zigbee2MQTT (powołując się na testy Intela z 2012) i liczne wątki na GitHubie potwierdzają drastycznie ograniczony zasięg koordynatora podłączonego bezpośrednio do portu USB 3.0. Zewnętrzne dyski SSD podłączone przez USB 3.0 to kolejne udokumentowane źródło zakłóceń.
Rozwiązanie: przedłużacz USB, najlepiej ekranowany. W praktyce często wystarcza już około 50 cm, ale ważniejsze niż konkretna długość jest realne odsunięcie anteny koordynatora od obudowy komputera, dysku SSD, portów USB 3.0, kabli HDMI i routera Wi-Fi. Dokumentacja Zigbee2MQTT rekomenduje tam, gdzie to możliwe, port USB 2.0 zamiast 3.0.
Adapter dostępny przez sieć: niektóre adaptery Zigbee (np. SLZB-06, dongle podpięte do konwertera USB-Ethernet) udostępniają port szeregowy przez TCP zamiast bezpośredniego USB, eliminując problem zakłóceń przy komputerze kosztem dodatkowej warstwy sieciowej: Zigbee2MQTT łączy się wtedy z nimi jako ze zdalnym interfejsem szeregowym, nie jako z samodzielną bramką MQTT. Przy porównywalnym sprzęcie i konfiguracji Ethernet bywa zwykle bardziej przewidywalny niż Wi-Fi, ale nie jest to reguła bezwzględna: dokumentacja Zigbee2MQTT ostrzega, że adaptery łączące się po Wi-Fi mogą mieć niższą stabilność, bo protokół szeregowy źle znosi utratę pakietów i zmienne opóźnienia.
Routing: dlaczego znikają urządzenia, które wcale się nie ruszyły
Każde urządzenie końcowe ma przypisanego rodzica (parent): router lub koordynator, przez który aktualnie komunikuje się z resztą sieci. Urządzenie zgodne ze standardem może próbować znaleźć nowego rodzica po utracie łączności, ale to, jak łatwo to zrobi, zależy od konkretnego firmware. Dokumentacja Zigbee2MQTT wprost wskazuje, że część modeli może pozostać odizolowana po utracie rodzica i wymagać ponownego wybudzenia, rejoin, a w skrajnym przypadku ponownego parowania: nie zakładaj więc automatycznie, że sieć „sama się naprawi”.
Kiedy router znika: bo ktoś wyłączył go z gniazdka albo wykręcił żarówkę pełniącą tę funkcję: wszystkie end device’y, które przez niego routowały ruch, tracą łączność, dopóki sieć nie przeprowadzi ponownego route discovery. To zajmuje czas i nie zawsze kończy się sukcesem automatycznie na starszych koordynatorach. Jeśli po migracji ze starego koordynatora urządzenia próbują dołączyć przez router, który zniknął z pamięci nowego koordynatora, dołączenie zawiedzie: stąd warto sprawdzić
coordinator_check opisany w sekcji o koordynatorach.Test przy koordynatorze dobrze eliminuje problem zasięgu i routingu, ale nie jest jedyną słuszną metodą: Zigbee2MQTT pozwala też sparować urządzenie przez konkretny, wybrany router (ograniczając do niego Permit join), co bywa lepszym rozwiązaniem dla urządzenia, które docelowo ma pracować daleko od koordynatora. Parowanie wszystkiego przy koordynatorze w dużej sieci potrafi przeciążyć jego child table i skutkować nieoptymalnym rodzicem od samego początku.
Diagnozowanie znikającego routera ułatwia wbudowana w Zigbee2MQTT mapa sieci, ale to migawka topologii zbudowana z danych o sąsiadach i tabeli routingu w chwili skanu: nie ciągły, w pełni aktualny podgląd drogi każdej ramki. Sam skan obciąża sieć i może zająć od kilkunastu sekund do kilku minut, chwilowo pogarszając responsywność, a od śpiących urządzeń bateryjnych może w ogóle nie uzyskać odpowiedzi. Podobnie LQI widoczne na mapie nie jest uniwersalnym „procentem zasięgu”: zwykle dotyczy tylko ostatniego skoku do danego urządzenia, a nie całej wieloskokowej trasy, więc wysoki LQI nie gwarantuje poprawnej komunikacji dwukierunkowej, a niski nie zawsze oznacza awarię.
Warstwowa diagnostyka: od żarówki do automatyzacji
Kiedy coś „nie działa”, warto iść warstwa po warstwie, zamiast zgadywać losowo.
Konfiguracja MQTT Discovery: uważaj na mieszanie starej i nowej składni Aktualna, poprawna konfiguracja to zagnieżdżona sekcja:
homeassistant: { enabled: true }: to jedyny obowiązkowy przełącznik, domyślnie integracja jest wyłączona. Starsze poradniki i konfiguracje mogły używać uproszczonej flagi homeassistant: true na najwyższym poziomie: to nie to samo, co ewentualnie spotykana gdzie indziej flaga discovery: true, a oba warianty nie powinny współwystępować w jednej konfiguracji. discovery_topic ma sensowną wartość domyślną (homeassistant) i trzeba go ustawiać jawnie tylko wtedy, gdy świadomie używasz innego prefiksu: musi wtedy zgadzać się z konfiguracją integracji MQTT w Home Assistant. To dokładnie ten obszar kryjący się za „działa w Z2M, ale nie widać w HA”.Birth message: to Home Assistant, nie broker Birth message publikuje integracja MQTT w Home Assistant (nie sam Mosquitto): domyślnie na
homeassistant/status z treścią online po starcie i offline przy rozłączeniu. Zigbee2MQTT nasłuchuje tego tematu i republikuje discovery, gdy Home Assistant zgłasza się jako „online”: jeśli podejrzewasz problem z tym mechanizmem, sprawdź opcje integracji MQTT w Home Assistant (Ustawienia → Urządzenia i usługi → MQTT → Konfiguruj), a nie konfigurację samego brokera.Zigbee2MQTT 2.x: zmiana obsługi akcji pilotów Rekomendowanym sposobem obsługi chwilowych akcji (naciśnięcia przycisków) są dziś MQTT device triggers: pojawiają się w Home Assistant dopiero po pierwszym wykonaniu danej akcji przez urządzenie, więc po sparowaniu pilota naciśnij każdy przycisk co najmniej raz i szukaj triggera w Ustawieniach → Automatyzacje i sceny → Wyzwalacze urządzenia, zamiast wyłącznie encji
sensor…action. Klasyczny sensor action to dziś opcja zgodności wsteczej (legacy_action_sensor, domyślnie wyłączona), a encje event są eksperymentalne i również wymagają świadomego włączenia (experimental_event_entities). Brak encji action po aktualizacji Zigbee2MQTT bywa więc po prostu skutkiem tej zmiany modelu integracji, a nie błędem configure: starsze automatyzacje oparte o sensor.action mogą wymagać przebudowy pod device triggers. Co do wersji Home Assistant: warto używać aktualnej, wspieranej wersji, ale nie ma potrzeby przywiązywać się do konkretnego numeru: to obszar, który zmienia się z każdą kolejną wersją Zigbee2MQTT.Re-interview, Reconfigure, reset: kiedy używać którego
Re-interview
Urządzenie sparowane, ale Z2M błędnie rozpoznaje jego możliwości. Bez usuwania z sieci: ponowne odpytanie o endpointy i klastry. Urządzenie bateryjne musi być obudzone (naciśnięty przycisk), inaczej operacja zwykle się nie powiedzie.
Reconfigure
Urządzenie rozpoznane, ale przestało raportować zmiany. Wymusza ponowne ustawienie reguł raportowania bez ingerencji w parowanie: tak samo wymaga wybudzenia urządzenia bateryjnego, dokładnie jak Bind, Unbind i OTA.
Reset (fizyczny)
Usuwa urządzenie z sieci i zeruje stan, wymagając pełnego ponownego parowania. Ostateczność dla urządzenia, które już działa w Twojej obecnej sieci, ale standardowy, prawidłowy pierwszy krok dla urządzenia kupionego z drugiej ręki, przenoszonego z innego huba albo o nieznanej konfiguracji.
Czego nie robić od razu: nie zaczynaj od resetu fizycznego już działającego urządzenia, jeśli problem może tkwić w warstwie MQTT Discovery albo konfiguracji integracji MQTT w Home Assistant: zresetujesz działające parowanie, a problem i tak zostanie.
Migracja koordynatora: bez parowania wszystkiego od nowa
Migracja koordynatora bez ponownego parowania wszystkich urządzeń jest możliwa, ale wymaga czegoś więcej niż zapamiętania trzech liczb. W grę wchodzi pełna kopia danych Zigbee2MQTT (w tym
database.db) razem ze zgodną kopią stanu samego koordynatora (coordinator_backup.json): obejmującą m.in. adres IEEE, kanał, PAN ID, extended PAN ID i klucz sieciowy. Backup i restore tego stanu są oficjalnie wspierane tylko dla adapterów zstack i ember: dla pozostałych sterowników (deCONZ, ezsp, zboss, zigate) taka gwarancja nie istnieje. Zigbee2MQTT ma wbudowaną funkcję backupu tych danych: warto go robić regularnie, nie tylko przed migracją.W obrębie tej samej rodziny adapterów (zstack → zstack lub ember → ember) ponowne parowanie zwykle nie jest wymagane: wyjątkiem jest migracja z Zigbee 1.2 (CC2530/CC2531) na Zigbee 3.0 (CC2652/CC1352), gdzie repairing jest wymagany ze względu na różnice w bezpieczeństwie sieci. Migracja między rodzinami (zstack ↔ ember) bywa możliwa i czasem nie wymaga ponownego parowania, ale oficjalnie nie jest wspierana, a rezultaty bywają różne: po takiej migracji sprawdź każde urządzenie z osobna; część routerów może wymagać ponownego sparowania blisko koordynatora przy selektywnym Permit join.
Po migracji problemem zwykle nie jest to, że urządzenia „nie wiedzą o nowym rodzicu”: jeśli sieć (IEEE, kanał, klucz) została zachowana identyczna, urządzenia nie muszą w ogóle wiedzieć, że fizycznie zmieniono sprzęt. Realnym źródłem kłopotów bywają: zmieniony adres IEEE koordynatora (jeśli nie został odtworzony), routery brakujące w pamięci nowego koordynatora (sprawdź
coordinator_check dla adapterów TI), niespójna albo niepełna kopia zapasowa oraz naturalnie długi cykl wybudzania urządzeń bateryjnych. Backup jest najbezpieczniejszym i oficjalnie zalecanym sposobem odzyskania sieci po awarii koordynatora, ale nie jedynym możliwym: w części przypadków da się też odtworzyć sieć z zachowanego katalogu danych albo z kopii całej instancji Home Assistant.Procedury per grupa urządzeń: skrócone odniesienie
Drzewo decyzji
Minimalny zestaw informacji do zgłoszenia problemu
Jeśli mimo tej diagnostyki utkniesz i będziesz szukać pomocy na forum albo w issues na GitHubie, przygotuj od razu pięć rzeczy:
Zanim opublikujesz log: zamaż lub usuń hasło do brokera MQTT, network key, PAN ID, adresy IEEE urządzeń, prywatne adresy IP i wszelkie tokeny. Debug log warto włączyć jeszcze przed uruchomieniem Permit join i zebrać całą próbę od początku, żeby nie wyciąć przypadkiem fragmentu istotnego dla diagnozy.
Czego nie znajdziesz w tym artykule
Świadomie pominąłem tu szczegółowy katalog funkcji poszczególnych urządzeń (znajdziesz go w artykułach o żarówkach, pilotach i czujnikach), procedury OTA (opisane przy poszczególnych kategoriach urządzeń) oraz rozbudowane przykłady automatyzacji i pełną teorię bindingu, które szerzej omawiam przy pilotach.
Co dalej
Źródła: oficjalna dokumentacja Zigbee2MQTT (FAQ, strony adapterów zStack/EmberZNet/deCONZ, konfiguracja Home Assistant/MQTT Discovery, Device Availability, Touchlink), dokumentacja integracji MQTT Home Assistant, repozytorium
Koenkk/zigbee2mqtt na GitHubie oraz forum Home Assistant Community.Stan wiedzy i nazewnictwo sterowników: sierpień 2026. Zigbee2MQTT rozwija się szybko (zmiany sterowników adapterów, obsługi discovery i akcji pilotów): przy rozbieżnościach z tym, co widzisz w swojej instalacji, kieruj się aktualną oficjalną dokumentacją.
W następnym artykule tej serii przechodzimy do konkretów: pełny katalog żarówek, lamp i sterowników LED IKEA wspieranych przez Zigbee2MQTT, wraz z ich realnymi parametrami i typowymi problemami. Przejdź do katalogu żarówek i sterowników LED →
