Sieć Z-Wave w Home Assistancie składa się z czterech elementów: adaptera podłączonego do serwera, serwera Z-Wave (w Home Assistant OS jest nim aplikacja Z-Wave JS, dawniej dodatek), integracji Z-Wave i samych urządzeń. Pierwsze urządzenie zwykle udaje się dodać w kilka minut. Kłopoty przychodzą później i prawie zawsze wynikają z kilku wcześniejszych decyzji: jaki adapter kupiłeś, gdzie stoi, czy zachowałeś klucze bezpieczeństwa i jak często urządzenia mogą wysyłać raporty.

Z-Wave działa poniżej 1 GHz, z dala od pasma 2,4 GHz, w którym tłoczą się Wi-Fi, Bluetooth, Zigbee i Thread. Dokładna częstotliwość zależy od regionu: w Unii Europejskiej klasyczne Z-Wave korzysta z 868,4 i 869,85 MHz, w USA z 908,42 i 916 MHz. Adapter serii 700 albo 800 można przestawić na inny region, urządzenia końcowe już nie. Kupuj więc urządzenia w wersji na swój region.

Wybierz adapter serii 800 i sprawdź jego oprogramowanie

Dokumentacja Home Assistanta zaleca na start adapter serii 800, a oficjalnie poleca Home Assistant Connect ZWA-2. Wśród adapterów serii 800, które według zgłoszeń działają, wymienia też HomeSeer SmartStick G8 i Zooz ZST39 LR. Adaptera serii 700 raczej nie warto kupować, a europejską wersję Aeotec Z-Stick 7 dokumentacja odradza wprost ze względu na słabe parametry radiowe.

Oprogramowanie układowe adaptera jest równie ważne jak model. Część wersji dla serii 700 i 800 ma błędy, które rozstrajają sieć albo sprawiają, że adapter przestaje odpowiadać, a nie ma wersji, o której wiadomo, że jest od nich całkiem wolna. Dla serii 800 dokumentacja radzi:

  • najlepiej SDK 7.23.x lub nowsze (przy zakupie nowego adaptera strona integracji wymaga oprogramowania co najmniej 7.23.2);
  • 7.22.x oraz od 7.17.2 do 7.19.x są w porządku;
  • unikaj wersji starszych niż 7.17.2 oraz od 7.20 do 7.21.3.

Wersja SDK nie musi się zgadzać z numerem oprogramowania podawanym przez producenta, więc w razie wątpliwości zapytaj producenta. Wybieraj ostrożnie, bo według dokumentacji Z-Wave JS oprogramowania kontrolera zwykle nie da się cofnąć do starszej wersji. Lepiej też wziąć adapter USB niż moduł na złączu GPIO, który trudniej przekazać do kontenera Dockera.

ZWA-2 nie przypomina typowego adaptera wielkości wtyczki USB. To spora antena na podstawce, w jednej wersji na cały świat (cena sugerowana 69 dolarów albo 59 euro). Fabrycznie jest ustawiony na region europejski, a Home Assistant sam przestawia go na region wynikający z lokalizacji w ustawieniach. Postaw go pionowo: ma w środku akcelerometr i szybko miga górną diodą, gdy stoi pod złym kątem.

Podłącz adapter przez przedłużacz USB

Według dokumentacji Home Assistanta wiele zgłaszanych problemów z Z-Wave bierze się z zakłóceń radiowych z portów USB samego serwera. Urządzenia nie chcą się dodać, dodają się bez szyfrowania, wysyłają przekłamane odczyty albo reagują z opóźnieniem. Twórcy integracji najpierw proszą o krótki przedłużacz USB 2.0, a potem o odbudowanie tras w sieci.

Poradnik rozwiązywania problemów Z-Wave JS dorzuca kolejne zalecenia: trzymaj adapter z dala od innych portów USB (zwłaszcza USB 3) i metalowych powierzchni, nie chowaj go z tyłu szafy serwerowej i postaw możliwie centralnie w domu. W statystykach adaptera widać RSSI tła, czyli poziom szumu, który słyszy radio. Powinien być jak najbliżej granicy czułości odbiornika, która dla serii 800 wynosi około -110 dBm.

Zainstaluj aplikację Z-Wave JS i zapisz klucze

  1. Podłącz adapter do komputera z Home Assistantem. Najczęściej zostanie wykryty sam. W oknie, które się pojawi, wybierz zalecaną instalację (Recommended installation). Home Assistant zainstaluje wtedy aplikację Z-Wave JS. Przypisz urządzenie do obszaru i kliknij Finish.
  2. Niektóre wersje Home Assistanta pytają w tym miejscu o klucze bezpieczeństwa sieci. Jeśli uruchamiasz Z-Wave pierwszy raz, zostaw pola puste i zatwierdź, a klucze zostaną wygenerowane. Jeśli adapter pracował już z urządzeniami dodanymi z szyfrowaniem, wpisz stary klucz sieci jako klucz S0.
  3. Poczekaj, aż aplikacja wystartuje. Gdy zobaczysz stronę urządzenia z adapterem, integracja jest gotowa.

Od razu skopiuj klucze w bezpieczne miejsce. Znajdziesz je w menu Ustawienia > Aplikacje > Z-Wave JS (Settings > Apps > Z-Wave JS), na karcie konfiguracji (Configuration): trzy klucze S2 i jeden S0. Urządzenia dodane z szyfrowaniem działają tylko z tymi kluczami, z którymi je dodano. Jeśli zgubisz klucze, na przykład przy przeprowadzce na nowy serwer, zamek z niepasującymi kluczami trzeba według dokumentacji Z-Wave JS usunąć z sieci, ewentualnie przywrócić w nim ustawienia fabryczne i dodać od nowa.

Jeśli adapter nie został wykryty, dodaj integrację Z-Wave ręcznie w menu Ustawienia > Urządzenia oraz usługi (Settings > Devices & services) przyciskiem dodawania integracji i sprawdź, czy kabel USB przesyła dane, a nie tylko zasilanie.

W Home Assistant Container aplikacji nie ma. Zalecany sposób to kontener Dockera z programem Z-Wave JS UI, w którym trzeba włączyć serwer WebSocket (WS Server). Adapter wskaż wtedy ścieżką /dev/serial/by-id/..., która nie zmienia się po ponownym uruchomieniu. Starsza aplikacja Z-Wave JS UI w Home Assistant OS jest stopniowo wycofywana, a dokumentacja opisuje przejście na aplikację Z-Wave JS bez ponownego dodawania urządzeń.

Region radiowy ustawia się według lokalizacji z menu Ustawienia > System > Ogólne (Settings > System > General). Żeby go zmienić ręcznie, wybierz region w polu Radio Frequency Region na karcie konfiguracji aplikacji. Tam, gdzie istnieje wariant z Long Range, wybierz go, na przykład Europe (Long Range). Urządzenia bez Long Range nadal będą z nim działać.

Rób kopię sieci, nie tylko Home Assistanta

Lista urządzeń w sieci jest zapisana w adapterze. Reszta tego, co Z-Wave JS wie o urządzeniach, już nie, więc przy pierwszym starcie integracja wypytuje każde urządzenie o jego możliwości (to tak zwane rozpoznanie urządzenia). Przy urządzeniach na baterie trwa to długo: według dokumentacji Z-Wave JS pierwsze rozpoznanie może zająć kilka godzin, chyba że wybudzisz urządzenie ręcznie, zwykle przyciskiem opisanym w instrukcji.

W ustawieniach łączności, na stronie Z-Wave (Settings > Connectivity > Z-Wave), pobierzesz kopię zapasową (Download backup). Plik zawiera zawartość pamięci nieulotnej adaptera, w tym sparowane urządzenia. Pobierz go przed przejściem na nowy adapter albo przed zresetowaniem starego i trzymaj razem z kluczami. Na tej samej stronie jest przywracanie z kopii (Restore from backup) i migracja adaptera (Migrate adapter), która przenosi sieć na nowy adapter bez ponownego parowania urządzeń.

Dodawaj urządzenia przez SmartStart i S2

Wejdź na stronę Z-Wave w ustawieniach łączności (Settings > Connectivity > Z-Wave) i wybierz Add device.

Urządzenie ze SmartStart rozpoznasz po oznaczeniu SmartStart i kodzie QR na pudełku albo obudowie. Zostaw je wyłączone, wybierz Scan QR code, zeskanuj kod, a dopiero potem włącz urządzenie albo przełącz je w tryb dodawania. Skanowanie kodu w przeglądarce wymaga HTTPS. Bez niego odczytaj kod innym programem i wklej jego treść jako tekst. Urządzenie z listy SmartStart dołączy samo w ciągu około 10 minut od włączenia w zasięgu sieci.

Urządzenie bez SmartStart przełącz w tryb dodawania tak, jak opisuje instrukcja. Przy S2 Home Assistant poprosi o PIN, czyli pierwsze pięć cyfr klucza DSK urządzenia. Często jest wydrukowany na obudowie i w dokumentacji. Zrób zdjęcie naklejki, zanim urządzenie zniknie w puszce podtynkowej.

Dwa dawne nawyki trzeba porzucić. Nie noś adaptera do urządzenia, żeby je dodać, bo zostaną po tym błędne trasy. I nie zaczynaj dodawania przyciskiem na adapterze, bo Home Assistant już tego nie obsługuje.

Z-Wave JS dzieli szyfrowanie na klasy bezpieczeństwa:

  • S2 Access Control dla zamków, bram garażowych i podobnych urządzeń;
  • S2 Authenticated dla systemów alarmowych, czujników i oświetlenia;
  • S2 Unauthenticated, to samo szyfrowanie, ale bez sprawdzenia, czy dodajesz właściwe urządzenie;
  • S0, starsza klasa.

Home Assistant wybiera S2 zawsze, gdy urządzenie je obsługuje, a po S0 sięga tylko wtedy, gdy musi. S0 mocno obciąża sieć: według poradnika Z-Wave JS każdy raport wymaga wymiany trzech komunikatów, dlatego czujników w ogóle nie warto tak szyfrować. Z zamkiem jest inaczej, bo bez szyfrowania jego podstawowe funkcje nie działają. Jeśli zamek dodał się bez szyfrowania, usuń go z sieci i dodaj ponownie.

Encje pojawiają się po zakończeniu rozpoznania, zwykle po kilku sekundach albo minutach. Niektóre urządzenia, na przykład piloty z przyciskami, nie tworzą żadnych encji, tylko wysyłają zdarzenia (przy przyciskach scen zwave_js_value_notification), które posłużą ci jako wyzwalacze automatyzacji.

Gdy urządzenie nie chce się dodać, przyczyna jest zwykle jedna z trzech:

  • Nadal należy do innej sieci. Najpierw je z niej usuń (wyklucz). Jeśli nie masz starego adaptera, na stronie Z-Wave wybierz Options > Remove foreign device. Pomoże też przywrócenie ustawień fabrycznych.
  • Region nie pasuje do urządzenia.
  • Urządzenie jest za daleko. Część starszych urządzeń przy dodawaniu zmniejsza moc nadawania. Przy parowaniu przenieś je bliżej, a gdy wszystko wróci na swoje miejsce, odbuduj trasy.

Sieć kratowa czy Long Range

W klasycznej sieci Z-Wave urządzenia zasilane z gniazdka i stale włączone przekazują dalej komunikaty innych. Urządzenia na baterie, czyli zamki, czujniki i wiele termostatów, tego nie robią. Sieć złożona z adaptera i jednego zamka do drzwi w ogóle nie jest siecią kratową. Klasyczna sieć mieści do 232 urządzeń.

Z-Wave Long Range to osobna sieć w układzie gwiazdy, obsługiwana przez ten sam adapter. Każde urządzenie Long Range łączy się bezpośrednio z adapterem i żadne nie przekazuje komunikatów urządzeń klasycznych. Takich urządzeń może być w sieci do 4000. Dodasz je wyłącznie przez SmartStart i wyłącznie w klasie S2 Access Control albo S2 Authenticated. Gdy zeskanujesz urządzenie obsługujące oba tryby, Home Assistant zapyta, do której sieci ma dołączyć:

  • Long Range, jeśli urządzenie stoi daleko od innych urządzeń albo w miejscu, gdzie wcześniej zrywało się połączenie. Może też dłużej działać na bateriach.
  • Sieć kratowa (opcja Mesh), jeśli już ją masz, bo każde nowe urządzenie zasilane z gniazdka ją wzmacnia.

Wybór nie jest ostateczny: żeby zmienić sieć, usuń urządzenie i dodaj je ponownie. Twórcy Z-Wave JS zalecają, żeby Long Range był świadomym wyborem użytkownika, a nie ustawieniem domyślnym.

W Europie Long Range to nowość. Z-Wave Alliance ukończyła europejską specyfikację w lutym 2024 roku, a SDK 7.23.1 firmy Silicon Labs przesunęło europejskie częstotliwości Long Range, przez co nie współpracują już z wcześniejszymi wersjami (7.22.x i 7.23.0). To jeszcze jeden powód, żeby aktualizować oprogramowanie adaptera.

Nie zasypuj sieci raportami

Poradnik Z-Wave JS nie owija w bawełnę: bezpośrednie połączenie przy dobrych warunkach przeniesie 10-20 komunikatów na sekundę, a stałe obciążenie tego rzędu na trasach z kilkoma przeskokami jest dla sieci „absolutnie zabójcze”. Wiele urządzeń fabrycznie wysyła raporty zbyt często, a najgorzej jest z czujnikami wielofunkcyjnymi i miernikami energii. Ustawienia raportów zmienisz na stronie urządzenia, w sekcji parametrów (Configure):

  • wyłącz raporty, z których nie korzystasz, na przykład napięcie i prąd z każdego gniazda listwy, jeśli potrzebujesz tylko kWh;
  • zamiast raportów co określony czas ustaw raporty przy zmianie, z progiem dobranym do odbiornika, na przykład 1 W dla żarówki LED, a 50 W lub więcej dla pralki;
  • raporty okresowe zostaw tylko jako zabezpieczenie, z długim odstępem, na przykład raz na godzinę;
  • wyłącz żądanie potwierdzenia (opcja „supervision”) przy raportach, które go nie potrzebują.

Odpytywanie urządzeń traktuj jako ostateczność. Z-Wave sam ich regularnie nie odpytuje, a akcja zwave_js.refresh_value służy do pojedynczych odczytów, na przykład odświeżenia jednej wartości, gdy w pokoju pojawi się ruch.

Po przeniesieniu urządzenia odbuduj jego trasy przyciskiem Rebuild routes na jego stronie. Opcja dla całej sieci (Options > Discover and assign new routes) generuje duży ruch, więc korzystaj z niej rzadko. Show map rysuje mapę tras, a Statistics pokazuje liczby dla każdego urządzenia. Jeśli jedno urządzenie ma tysiące raportów przychodzących, a pozostałe po kilka, to prawdopodobnie jest źle skonfigurowane albo ma słabe połączenie.

Gdy coś działa nie tak

Urządzenie, które co chwilę przestaje odpowiadać i wraca, a w dzienniku widać „NoAck”, ma słabe połączenie z adapterem. Sprawdź wtedy jeszcze raz, gdzie stoi adapter, czy jest na przedłużaczu i jak często urządzenia wysyłają raporty. Jeśli urządzenie jest opisane jako „Unknown Manufacturer”, to albo Z-Wave JS nie skończył go jeszcze rozpoznawać, albo nie ma dla niego pliku opisu. Nie znaczy to, że nie będzie działać. Do zgłoszenia błędu włącz w menu integracji szczegółowy dziennik (Enable debug logging), odtwórz problem i wyłącz dziennik. Home Assistant zaproponuje wtedy pobranie zapisanych wpisów.