Przekaźniki i gniazdka Shelly to jedne z najprostszych urządzeń Wi-Fi do używania z Home Assistantem bez chmury. Oficjalna integracja Shelly rozmawia z każdym urządzeniem bezpośrednio w sieci lokalnej, a urządzenie samo wysyła zmiany stanu, zamiast czekać, aż ktoś o nie zapyta. Światło włączone ze ściany pojawia się w Home Assistancie praktycznie od razu i wszystko działa także wtedy, gdy nie ma internetu.

Prosto z pudełka Shelly jest jednak przygotowane pod aplikację producenta: ma otwarty punkt dostępowy do konfiguracji, połączenie z chmurą i panel WWW bez hasła. Poniżej opisuję, jak je ustawić, żeby rządził Home Assistant, urządzenie było zabezpieczone w sieci, a naciśnięcia przycisków i pomiary energii trafiały tam, gdzie da się z nich skorzystać.

Którą generację masz

Shelly wydało cztery generacje urządzeń i integracja obsługuje wszystkie. Różnica ma znaczenie przy konfiguracji:

  • Generacja 1 (starsze Shelly 1, 2.5, Plug S i podobne) wysyła zmiany protokołem CoIoT. Wymaga drobnego ręcznego ustawienia na każdym urządzeniu.
  • Generacja 2 i nowsze (modele Plus, Pro, Gen3 i Gen4) używają protokołu RPC. Urządzenia zasilane z sieci nie potrzebują dodatkowej konfiguracji.
  • Shelly BLU to czujniki i przyciski Bluetooth. Nie dodaje się ich przez integrację Shelly, tylko przez integrację BTHome.

Model i wersję oprogramowania pokazuje stopka panelu WWW. Integracja wymaga oprogramowania w wersji co najmniej 1.9 w generacji 1 i co najmniej 1.0 w generacji 2, więc bardzo stare urządzenia najpierw zaktualizuj.

Krok 1: podłącz urządzenie do Wi-Fi bez aplikacji

Nowe albo zresetowane Shelly uruchamia własny punkt dostępowy o nazwie w rodzaju ShellyPlus1-XXXXXXXXXXXX, gdzie końcówka to identyfikator urządzenia. Połącz się z nim telefonem albo laptopem i otwórz w przeglądarce http://192.168.33.1. To lokalny panel WWW. Działa bez konta i bez internetu.

W Settings > Wi-Fi wybierz swoją sieć i wpisz hasło. Nowsze modele, na przykład z generacji Gen3, mogą zapamiętać dwie sieci i przełączyć się na drugą, gdy pierwsza jest niedostępna. Po kilku sekundach panel pokaże nowy adres w sieci domowej. Otwórz go i dalej pracuj już tam.

Od razu warto zrobić dwie rzeczy:

  1. Ustal stały adres IP. Ustaw statyczny adres w ustawieniach Wi-Fi albo, co lepsze, zrób rezerwację DHCP na routerze. Stały adres ułatwia szukanie usterek, a niektóre funkcje, na przykład wzmacniacz zasięgu Shelly, działają tylko ze statycznym albo zarezerwowanym adresem.
  2. Zamknij punkt dostępowy. Według dokumentacji Shelly punkt dostępowy urządzenia jest domyślnie siecią otwartą. Gdy urządzenie jest już w Wi-Fi, wyłącz go w ustawieniach punktu dostępowego albo przynajmniej ustaw hasło. Inaczej każdy w zasięgu może się do niego podłączyć i dostać do panelu WWW.

Krok 2: ustaw hasło na urządzeniu

Urządzenia generacji 2 i nowszych obsługują uwierzytelnianie lokalnego API i panelu WWW. Domyślnie jest wyłączone. Włącz je w panelu WWW urządzenia w ustawieniach uwierzytelniania (w modelach Gen3 to Settings > Authentication) i wybierz hasło.

Kilka szczegółów z dokumentacji API Shelly:

  • Nazwa użytkownika to zawsze admin. Wybierasz tylko hasło.
  • Ochrona korzysta z uwierzytelniania HTTP digest z SHA-256. Obejmuje panel WWW i interfejs RPC przez HTTP i WebSocket, ale nie MQTT ani wychodzący WebSocket, bo to połączenia nawiązywane przez samo urządzenie.
  • Niewielka część informacji, na przykład podstawowe dane urządzenia, zostaje dostępna bez hasła, żeby działało wykrywanie.
  • Oprogramowanie 2.0.0 i nowsze spowalnia zgadywanie haseł. Po 11 nieudanych próbach urządzenie każe klientowi odczekać przed kolejną, czas oczekiwania rośnie z liczbą błędów, a od 40 nieudanych prób wynosi 5 minut. Zablokowane żądania dostają odpowiedź HTTP 429.

Nie myl tego z kodem PIN w aplikacji Shelly. Ten PIN chroni urządzenie tylko w aplikacji i nie przeszkodzi nikomu, kto jest w tej samej sieci.

Home Assistant zapyta o nazwę użytkownika i hasło przy dodawaniu chronionego urządzenia. Jeśli ustawisz hasło na urządzeniu, które już jest dodane, integracja poprosi o ponowne uwierzytelnienie.

Krok 3: dodaj urządzenie do Home Assistanta

W większości sieci Home Assistant sam wykryje urządzenie i pokaże je jako wykryte w Ustawienia > Urządzenia oraz usługi (Settings > Devices & services). Wybierz Dodaj, potwierdź i w razie potrzeby wpisz dane logowania.

Jeśli wykrywanie go nie znajdzie (częste, gdy Shelly siedzi w innym VLAN-ie), dodaj je ręcznie: Ustawienia > Urządzenia oraz usługi > Dodaj integrację > Shelly i wpisz adres IP urządzenia. Pole portu jest potrzebne tylko dla urządzeń osiąganych przez wzmacniacz zasięgu Shelly.

Urządzenia na baterie, na przykład Shelly H&T, przez większość czasu śpią. Tuż przed dodaniem obudź je przyciskiem na obudowie.

Generacja 1: włącz CoIoT

Urządzenia generacji 1 wysyłają zmiany do Home Assistanta tylko wtedy, gdy CoIoT jest skonfigurowane. W panelu WWW urządzenia otwórz Internet & Security > ADVANCED - DEVELOPER SETTINGS, zaznacz Enable CoIoT i w polu CoIoT peer wpisz adres Home Assistanta z portem 5683, na przykład 192.168.1.10:5683. Zapisz i uruchom urządzenie ponownie.

Dokumentacja Home Assistanta zaleca takie ustawienie (unicast) w każdym przypadku, a dla urządzeń na baterie uznaje je za obowiązkowe. Jeśli zmiany nie docierają, Home Assistant pokaże zgłoszenie naprawy dla tego urządzenia. Jeśli nie widzisz pola CoIoT peer, oprogramowanie jest za stare.

Generacja 2 i nowsze: urządzenia na baterie i wychodzący WebSocket

Urządzenia generacji 2 i nowszych zasilane z sieci niczego więcej nie potrzebują. Te na baterie wysyłają dane przez wychodzący WebSocket, który integracja zwykle ustawia sama. Jeśli Home Assistant nie potrafi ustalić własnego adresu wewnętrznego albo urządzenie pracowało wcześniej z inną instancją Home Assistanta, ustaw to ręcznie w panelu WWW urządzenia w Settings > Connectivity > Outbound WebSocket: włącz opcję i wpisz ws://<IP Home Assistanta>:8123/api/shelly/ws. Jeśli Home Assistant działa po HTTPS, użyj wss://.

Urządzenia w osobnym VLAN-ie

Integracja potrzebuje ruchu w obie strony między Home Assistantem a urządzeniami:

  • Home Assistant musi mieć dostęp do każdego Shelly po HTTP (port 80) albo HTTPS (port 443, więcej niżej).
  • Urządzenia generacji 1 muszą mieć dostęp do Home Assistanta na porcie UDP 5683 (CoIoT).
  • Urządzenia generacji 2 i nowszych na baterie muszą mieć dostęp do Home Assistanta na jego porcie WWW, zwykle 8123, dla wychodzącego WebSocketu.

Urządzeniom generacji 2 i nowszych zasilanym z sieci wystarczy pierwsza reguła.

Krok 4: wyłącz chmurę (albo świadomie ją zostaw)

Gdy urządzeniem steruje Home Assistant, połączenie z Shelly Cloud jest opcjonalne. Domyślnie jest włączone. Wyłączysz je w panelu WWW w Settings > Cloud (w niektórych modelach Connectivity > Cloud). Dokumentacja Shelly mówi jasno, co się wtedy stanie: aplikacja Shelly straci dostęp do urządzenia spoza sieci lokalnej.

Jeśli i tak łączysz się z Home Assistantem zdalnie, nic nie tracisz. Jeśli ktoś w domu korzysta z aplikacji Shelly poza domem, zostaw chmurę włączoną i równolegle używaj integracji lokalnej. Jedno nie przeszkadza drugiemu.

Krok 5: dopasuj encje do instalacji

Domyślnie każdy przekaźnik staje się encją switch. Dwa ustawienia urządzenia zmieniają to, co utworzy Home Assistant, i oba lepiej ustawić przed pisaniem automatyzacji.

Typ odbiornika. Jeśli przekaźnik zasila światło, ustaw w panelu WWW dla tego wyjścia zewnętrzny typ odbiornika (External consumption type) na light. Integracja utworzy wtedy encję light zamiast przełącznika, więc przekaźnik trafi do pozostałych świateł w obszarze i zadziała z akcjami dla świateł.

Tryb wejścia. Łącznik ścienny podłączony do Shelly można ustawić jako Switch albo Button:

  • Przy Switch (zwykły łącznik dwupozycyjny) Home Assistant dostaje czujnik binarny ze stanem wejścia.
  • Przy Button (łącznik chwilowy, czyli przycisk) Home Assistant dostaje zamiast tego encję zdarzeń, a urządzenie zgłasza pojedyncze, podwójne, potrójne i długie naciśnięcia. Jeden fizyczny przycisk może wtedy robić kilka rzeczy.

Jeśli przycisk ma tylko wysyłać zdarzenia do Home Assistanta, a nie przełączać przekaźnika bezpośrednio, ustaw typ wyjścia na Detached (odłączony). Wtedy przekaźnikiem niezależnie sterują automatyzacje.

Podwójne naciśnięcie odłączonego przycisku może na przykład zgasić wszystkie światła na parterze:

alias: "Przycisk w przedpokoju: podwójne naciśnięcie gasi parter"
triggers:
  - trigger: state
    entity_id: event.hallway_button_input_0
conditions:
  - condition: template
    value_template: "{{ trigger.to_state.attributes.event_type == 'double_push' }}"
actions:
  - action: light.turn_off
    target:
      area_id: downstairs

Identyfikator encji zależy od nazwy urządzenia. Stan encji zdarzeń to czas ostatniego zdarzenia, więc zmienia się przy każdym naciśnięciu, nawet jeśli rodzaj naciśnięcia się powtarza. Urządzenia generacji 2 i nowszych zgłaszają btn_down, btn_up, single_push, double_push, triple_push i long_push. Generacja 1 używa single, double, triple, long, single_long i long_single.

Przy każdym wyjściu sprawdź też ustawienie Action on power on. Decyduje, czy po zaniku zasilania przekaźnik się włączy, zostanie wyłączony, czy wróci do ostatniego stanu. Przy oświetleniu zwykle najlepszy jest powrót do ostatniego stanu. Przy grzejniku albo pompie zastanów się, co ma się stać, gdy prąd wróci, a w domu nikogo nie ma.

Pomiar energii

W modelach z pomiarem mocy integracja tworzy czujnik mocy w watach i czujnik energii, który liczy zużycie w kWh. Czujnik energii to suma, która tylko rośnie, czyli dokładnie to, czego oczekuje panel energii w Home Assistancie. Dodaj go w ustawieniach panelu energii w sekcji poszczególnych urządzeń (Individual devices). Resztę tej konfiguracji opisuje nasz artykuł o panelu energii.

Dokumentacja Home Assistanta wskazuje tu jedną zależność: Shelly potrzebuje działającej synchronizacji czasu (SNTP) do funkcji takich jak pomiar mocy. Jeśli odczyty wyglądają podejrzanie, sprawdź w panelu WWW, czy ustawiony serwer czasu jest osiągalny. Dotyczy to zwłaszcza VLAN-u bez dostępu do internetu, gdzie może być trzeba wskazać serwer NTP w sieci lokalnej.

Niektóre urządzenia mają też wbudowane zabezpieczenia, takie jak maksymalna moc, prąd i napięcie. Po przekroczeniu limitu przekaźnik się wyłącza. Dzieje się to w samym urządzeniu, bez udziału Home Assistanta, czyli dokładnie tam, gdzie limit bezpieczeństwa powinien działać.

Aktualizacje oprogramowania i HTTPS

Integracja tworzy dla każdego urządzenia encję aktualizacji oprogramowania, więc aktualizacje Shelly pojawiają się obok innych w Home Assistancie i da się je stamtąd zainstalować. Wyjątkiem są urządzenia na baterie: Home Assistant pokaże, że jest nowa wersja, ale nie uruchomi aktualizacji, bo urządzenie przez większość czasu śpi.

Oprogramowanie 2.0.0 wprowadziło w urządzeniach generacji 2 i nowszych tryb Enhanced Security, związany z unijną dyrektywą w sprawie urządzeń radiowych (RED). Urządzenia, które wyszły z fabryki z wersją 2.0.0 lub nowszą, od razu używają HTTPS. Urządzenia zaktualizowane ze starszej wersji działają jak dotąd, dopóki nie włączysz Enhanced Security ręcznie. Integracja sama wykrywa HTTPS i łączy się na porcie 443. Opcję Verify SSL włącz tylko wtedy, gdy urządzenie ma certyfikat podpisany przez urząd certyfikacji, któremu ufa Home Assistant. Jeśli nie instalujesz takiego certyfikatu, zostaw ją wyłączoną.

Dodatkowo: pośrednik Bluetooth w każdym przekaźniku

Urządzenia generacji 2 i nowszych zasilane z sieci mogą też przekazywać do Home Assistanta rozgłoszenia Bluetooth. W opcjach integracji wybierz tryb skanowania Bluetooth. Dokumentacja zaleca tryb Auto: przez większość czasu nasłuchuje pasywnie i skanuje aktywnie tylko wtedy, gdy trzeba, co oszczędza około 95 procent energii, którą czujniki Bluetooth tracą przez skanowanie. Shelly nie obsługuje aktywnych połączeń, więc nadaje się do czujników temperatury i przycisków BLU, ale nie do urządzeń, które trzeba sparować.

Typowe błędy

  • Otwarty punkt dostępowy do konfiguracji. To pierwsza rzecz do zamknięcia, gdy urządzenie jest już w Wi-Fi.
  • Przekonanie, że PIN z aplikacji chroni urządzenie. Dostęp lokalny chroni tylko hasło uwierzytelniania.
  • Brak ustawionego CoIoT peer w generacji 1. Urządzenie działa, ale Home Assistant nie dostaje od niego zmian na bieżąco i pokazuje zgłoszenie naprawy.
  • Zablokowany ruch powrotny między VLAN-ami. Sterowanie z Home Assistanta działa, ale urządzenia na baterie i urządzenia generacji 1 przestają zgłaszać stan.
  • Odłączony przycisk bez automatyzacji. Gdy Home Assistant nie działa, przycisk nic nie robi. Zastanów się, czy w danym pomieszczeniu to akceptowalne. Przy głównym świetle zwykle bezpieczniej nie odłączać wejścia.