W ostatnim artykule dowiedzieliśmy się czym jest protokół MQTT, do czego służy, jak działa oraz jak uruchomić serwer, który zarządza całą komunikacją. Tym razem dowiemy się jak sterować urządzeniem wykorzystującym wspomniany protokół. Zaczniemy od prostego przełącznika, który posiada dwa stany: włączony i wyłączony. Do najpopularniejszych urządzeń tego typu należy Sonoff Basic (wersja R2 lub R3) oraz Shelly 1. Oba urządzenia możecie kupić np.: w sklepie  Botland za ok. 35 PLN Sonoff i 60 PLN Shelly.

To na ich przykładzie wyjaśnię integrację pomiędzy urządzeniem MQTT, a Home Assistant. Jednak należy pamiętać, że ze względu na naturę protokołu i samej integracji poniższy opis będzie miał zastosowanie do większości innych urządzeń.

Zatem naszą integrację musimy zacząć trochę inaczej niż dla innych wcześniejszych przykładów. Różnica polega na tym, że urządeń MQTT nie integrujemy tak naprawdę z Home Assistant, a komunikujemy się z nimi przez serwer - broker. Wszystko dlatego, że charakterystyka protokołu jak już wiemy z poprzedniego artykułu bazuje na wzorcu publikacja/subskrypcja. Dlatego pierwszym krokiem jest połączenie urządzenia z naszym brokerem. 

UWAGA: 
Poradnik ten zakłada, że przełącznik Shelly 1 lub Sonof Basic jest podłączony do prądu i działa poprawnie.
Poradnik ten zakłada, że na przełączniku Sonoff Basic uruchomione jest oprogramowanie Tasmota, a na Shelly 1 oprogramowanie oryginalne.

Krok 1

Dla powyższych dwóch urządzeń sprawa podłączenie do brokera wygląda następująco:

Shelly 1

  1. Łączymy się na interfejs WWW przełącznika Shelly 1 wpisując jego adres IP w przeglądarce
  2. Następnie wybieramy opcję Internet & Security
  3. Rozwijamy sekcję Advanced - Developer Settings
  4. Włączamy opcję Enable action execution via MQTT
  5. w polu username/password podajemy użytkownika i hasło wymagane do połączenia z naszym brokerem
  6. W polu Server wpisujemy IP i PORT brokera w formacie IP:PORT
  7. Zaznaczamy opcję Use custom MQTT prefix i tam podajemy prefix po jakim rozpoznamy urządzenie - to jest ważny punkt całej konfiguracji dobrze jak prefix jest jednoznaczny w stylu shelly_swiatlo_goscinny
  8. Pozostałe opcje możemy zostawić bez zmian. Zalecam tylko włączenie opcji Retain aby na serwerze był zapamiętywany ostatni stan przełącznika.
  9. Zapisujemy zmiany - Save

Sonoff Basic (Tasmota)

  1. Łączymy się na interfejs WWW przełącznika Sonoff wpisując jego adres IP
  2. Wybieramy sekcję Configuration
  3. Następnie Configure MQTT
  4. W polu Host podajemy adres ip brokera
  5. W polu Port podajemy port brokera
  6. W polu Client podajemy nazwę klienta jaką ma się przedstawiać urządzenie - możemy zostawić bez zmian
  7. w polu user/password podajemy użytkownika i hasło wymagane do połączenia z naszym brokerem
  8. W polu Topic podajemy temat (tak naprawdę część tematu) na jaki urządzenie ma publikować i odczytywać informacje - to jest ważny punkt całej konfiguracji dobrze jak ta wartość jest jednoznaczna w stylu sonoff_swiatlo_dol
  9. Pozostałe opcje pozostawiamy bez zmian.
  10. Zapisujemy zmiany - Save

Krok 2

W tym kroku łączymy nasz serwer HA z serwerem MQTT Broker. W tym celu z interfejsu dodajemy nową integrację (oczywiście wiemy już jak to robić) o wszystko mówiącej nazwie MQTT. Konfigurujemy ją zgodnie z poniższym opisem:

Pośrednik - IP/Nazwa naszego brokera
Port - Numer portu naszego brokera
Użytkownik/hasło - użytkownik i hasło wymagane do logowania się na serwerze brokera
Włącz wykrywanie - umożliwia automatyczne wykrywanie urządzeń mqtt

Krok 3

W tym kroku musimy stworzyć w Home Assistant odpowiednią encję, która będzie nam reprezentowała urządzenie jakim chcemy zarządzać. Dla przełączników musimy stworzyć encję typu switch dla czujnika musielibyśmy stworzyć encję typu sensor dla oświetlenia typu light itp. itd. natomiast dla każdego typu platformą jest mqtt. Przykładowe wpisy w pliku configuration.yaml dla naszych przełączników mogą wyglądać następująco:

Sonoff Basic

switch:
  - platform: mqtt
    name: "Nazwa wyświetlana"
    state_topic: "stat/sonoff-swiatlo-dol/POWER"
    command_topic: "cmnd/sonoff-swiatlo-dol/power"
    payload_on: "ON"
    payload_off: "OFF"

Shelly 1

switch:
  - platform: mqtt
    name: "Goscinny swiatlo"
    state_topic: "shellies/shelly_swiatlo_goscinny/relay/0"
    command_topic: "shellies/shelly_swiatlo_goscinny/relay/0/command"
    payload_on: "on"
    payload_off: "off"

A teraz, co to wszystko oznacza? Zacznijmy od samego początku.

Pierwsze parametry są dosyć jasne więc szybko. Na początek oznaczenie typu urządzenia. W naszym przypadku jest to switch bo konfigurujemy przełączniki. Kolejne, platform mqtt oznacza, że będziemy używać konfiguracji MQTT. Parametr name to już wszystkim dobrze znana informacja, która między innymi jest wyświetlana na interfejsie HA. Następne parametry są ciekawsze i specyficzne dla MQTT. Omówmy je więc szerzej:

state_topic i command_topic - są to dwa parametry, które określają na jakim temacie urządzenie publikuje informacje o swoim stanie - state_topic (czyli np.: włączony/wyłączony) oraz na jakim temacie subskrybuje/nasłuchuje poleceń do wykonania - command_topic.

Tu na moment się zatrzymamy i podam kilka dodatkowych informacji:

  1. Należy mieć świadomość, że większość urządzeń używających MQTT w momencie uruchomienia subskrybuje kilka różnych tematów. Te tematy mogą się różnić względem rodzaju urządzenia, producenta itp. Jak widzimy na powyższym przykładzie command_topic dla Sonoff Basic jest inny niż command_topic dla Shelly 1 chociaż w założeniach oba to przełączniki praktycznie z taką samą funkcjonalnością. Jedyne co jest wspólne dla tych wszystkich urządzeń to fakt, że tematy zawierają prefix/nazwa którą nadajemy w stylu swiatlo_goscinny. Jednak to nie jest kompletny temat. Aby wszystko poprawnie działało musimy znać poprawny temat dla definiowanego przez nas urządzenia. Zarówno dla odczytania stanu jak również dla wysyłania poleceń. Niestety nie ma jednego sposobu na pozyskanie tych informacji. Często można je wyczytać na urządzeniu lub z dokumentacji producenta, internetu, logów brokera itp.
  2. Należy pamiętać, że urządzenia które mogą być sterowane przez protokół MQTT będą miały osobny temat do publikowania informacji o swoim stanie, a osobny temat, który będą subskrybować aby odbierać polecenia. Dlatego raczej sytuacja kiedy state_topic i command_topic to ten sam temat nie powinna mieć miejsca.
  3. Istnieje jeszcze parametr availability_topic, który w powyższym przykładzie jest nieużywany, a może służyć do przekazania informacji o dostępności bądź niedostępności danej encji. Oczywiście jego wartością powinien być temat, który zawiera taką informację.

Kolejne parametry to payload_on i payload_off - podajemy tu wartość jaka świadczy o stanie włączonym - payload_on i wyłączonym - payload_off. W skrócie taka wartość zostanie wysłana jako wiadomość na temat command_topic gdy będziemy włączać/wyłączać urządzenie. Wartość ta również będzie przyrównywana do wiadomości jaka pojawia się na temacie state_topic i gdy będzie równa danej wartości to HA uzna, że urządzenie jest w stanie włączonym lub wyłączonym. Jeżeli z jakiegoś powodu urządzenie ma inną wiadomość na włączenie/wyłączenie urządzenia niż na przekazanie stanu (np.: wiadomość on włącza urządzenie ale urządzenie informuje stan włączony podając wiadomość online) to możemy użyć dodatkowych parametrów state_on i state_off. Wtedy tylko ta wartość z tych parametrów będzie przyrównywana do publikowanych wiadomości w temacie state_topic.

Istnieje również parametr payload_available i payload_not_available i jest on powiązany z availability_topic. Podajemy tam wartości, które świadczą o tym, że urządzenie jest dostępne lub niedostępne.

Jest jeszcze kilka innych parametrów dla przełączników ale mają one mniejsze znaczenie i dla znaczącej większości przypadków wystarczą ich standardowe ustawienia. Dlatego nie chcąc przedobrzyć z ilością informacji na raz pominę je w tym artykule.

Oczywiście należy pamiętać, że różne typy urządzeń posiadają różne parametry. Na przykład oświetlenie, które wspiera protokół MQTT posiada parametr brightness_command_topic, który umożliwia ustawienie jasności oświetlenia i brightness_state_topic, który umożliwia odczytanie aktualnie ustawionej jasności oświetlenia. Jednak metoda ich używania jest najczęściej podobna do tej przeze mnie opisanej.

Gdy dodamy odpowiednią konfigurację nie pozostaje nic innego jak restart serwera HA. Oczywiście najpierw uruchamiamy weryfikację pliku konfiguracyjnego.

Krok 4

Gdy serwer ponownie się uruchomi powinniśmy mieć nasze nowe encje.  Pozostaje dodać stosowną do naszych potrzeb kartę powiązaną z daną encją i możemy śmiało włączać i wyłączać nasz przełącznik, a tym samym wszystko co jest do niego podłączone. Grtauluję!

To wszystko w tym artykule. Tradycyjnie komentarze są wasze. Do przeczytania za 2 tygodnie.