MQTT to lekki protokół, w którym jedni klienci publikują wiadomości w tematach, a inni te tematy subskrybują. Pośrodku stoi broker, który rozsyła wiadomości. Tak działa Zigbee2MQTT, wiele urządzeń z Tasmotą, ESPHome w trybie MQTT i sporo czujników zrobionych samodzielnie. Home Assistant też może być takim klientem, wystarczy wskazać mu brokera.

Home Assistant zaleca oficjalną aplikację Mosquitto broker (dawniej dodatek Mosquitto) na Home Assistant OS razem z integracją MQTT. Pokazuję, jak to skonfigurować, jak założyć konta dla urządzeń, jak działa wykrywanie i jak wysłać testową wiadomość, żeby sprawdzić, czy wszystko działa.

Broker i integracja to dwie różne rzeczy

Na początku łatwo pomylić dwie rzeczy:

  • Broker to serwer, który odbiera, przechowuje i przekazuje wiadomości. Na Home Assistant OS zwykle jest to aplikacja Mosquitto broker.
  • Integracja MQTT to klient po stronie Home Assistanta. Łączy się z brokerem, odbiera komunikaty wykrywania i pozwala publikować wiadomości z automatyzacji oraz z interfejsu.

Potrzebujesz obu. Dopóki nie skonfigurujesz integracji, sama aplikacja niczego w interfejsie nie zmieni. Z kolei integracja nie połączy się, jeśli broker jest nieosiągalny.

Home Assistant wymaga, żeby broker obsługiwał MQTT w wersji 5, i oficjalna aplikacja Mosquitto to potrafi. Dokumentacja MQTT odradza ActiveMQ i wtyczkę MQTT do RabbitMQ, bo obie źle obsługują zachowywane wiadomości („retained”).

Zainstaluj Mosquitto i podłącz Home Assistanta

Możesz zacząć od integracji albo od aplikacji. Oba sposoby są równie dobre.

Sposób A: aplikację instaluje integracja. Dodaj integrację MQTT w Ustawienia > Urządzenia oraz usługi (Settings > Devices & services). Gdy Home Assistant zaproponuje oficjalną aplikację Mosquitto broker, zgódź się. Home Assistant sam utworzy nazwę użytkownika i hasło do swojego połączenia i nigdzie ich nie pokazuje. Nie musisz ich wpisywać.

Sposób B: najpierw aplikacja.

  1. Wejdź w Ustawienia > Aplikacje > Zainstaluj aplikację (Settings > Apps > Install app).
  2. Znajdź Mosquitto broker i zainstaluj.
  3. Uruchom aplikację i odczekaj kilka minut. Zajrzyj do dziennika i sprawdź, czy nie ma w nim błędów.
  4. Wejdź w Ustawienia > Urządzenia oraz usługi. MQTT powinno się tam pojawić jako wykryta integracja. Wybierz ją, w razie potrzeby włącz wykrywanie MQTT (korzystają z niego Zigbee2MQTT i podobne narzędzia) i zatwierdź.

Jeśli po poprzednim brokerze została stara integracja MQTT, usuń ją i uruchom ponownie Home Assistanta. Dopiero wtedy wykryje nowego Mosquitto.

Jeśli oficjalna aplikacja i integracja są połączone w ten sposób, przy ponownej instalacji aplikacji powstaje nowe hasło wewnętrzne. Nie musisz go nigdzie wpisywać, bo integracja połączy się ponownie już z nowym hasłem. Zanim usuniesz aplikację, zapisz dodatkowe konta z jej opcji, bo te nie wrócą same.

Załóż użytkownika dla urządzeń

Home Assistant łączy się z Mosquitto pod zastrzeżonymi nazwami. Nie zakładaj użytkowników homeassistant ani addons, bo używa ich sam system.

Dla Zigbee2MQTT, płytek ESP, MQTT Explorera i wszystkiego innego, co musi się zalogować do brokera:

  1. Włącz Tryb zaawansowany (Advanced Mode) w profilu Home Assistanta, jeśli nie widzisz menu Użytkownicy.
  2. Wejdź w Ustawienia > Osoby > Użytkownicy (Settings > People > Users) i utwórz osobne konto, przeznaczone tylko do MQTT, a nie konto administratora, którego używasz na co dzień.
  3. Wpisz tę nazwę użytkownika i hasło w urządzeniach.

Możesz też dodać lokalnych użytkowników w opcji logins aplikacji Mosquitto, ale nie musisz. Konta Home Assistanta działają z brokerem bez żadnej dodatkowej konfiguracji. Lokalne wpisy logins przydają się wtedy, gdy chcesz mieć do brokera osobne hasło, niezwiązane z logowaniem do Home Assistanta.

Ta aplikacja nie obsługuje połączeń anonimowych. Każdy klient musi podać nazwę użytkownika i hasło. Ustawienie allow_anonymous true we własnej konfiguracji nie zadziała tak, jak można by się spodziewać.

Porty i TLS

Domyślnie Mosquitto nasłuchuje na:

  • 1883 - zwykły MQTT
  • 1884 - MQTT przez WebSockets
  • 8883 i 8884 - to samo z szyfrowaniem TLS, jeśli umieścisz certyfikat i klucz w folderze ssl Home Assistanta i ustawisz certfile oraz keyfile w opcjach aplikacji

Porty bez szyfrowania wyłączysz, usuwając ich numery na karcie sieci w ustawieniach aplikacji. Klienci muszą wtedy łączyć się przez porty TLS i ufać certyfikatowi serwera.

Opcja require_certificate: true idzie o krok dalej: klient musi przedstawić certyfikat podpisany przez urząd certyfikacji z pliku cafile, a sama nazwa użytkownika nie wystarczy. Zostaw false, chyba że na pewno potrzebujesz wzajemnego uwierzytelniania TLS.

Wykrywanie MQTT

Gdy wykrywanie jest włączone (a domyślnie jest), urządzenia same się zgłaszają: publikują swoją konfigurację w formacie JSON w temacie zaczynającym się od prefiksu wykrywania. Domyślnie jest nim homeassistant. Temat dla pojedynczego komponentu wygląda zwykle tak:

homeassistant/sensor/<object_id>/config

a gdy kilka encji jednego urządzenia przychodzi w jednej wiadomości, tak:

homeassistant/device/<object_id>/config

Urządzenie wysyła konfigurację, a Home Assistant tworzy na jej podstawie encje. Dzięki temu Zigbee2MQTT, Tasmota, OpenMQTTGateway i wiele innych narzędzi pojawia się w Home Assistancie prawie bez pisania YAML. Listę narzędzi, które obsługują wykrywanie, znajdziesz na stronie integracji MQTT. Są na niej między innymi Zigbee2MQTT i ESPHome.

Prefiks wykrywania zmienisz albo wyłączysz w opcjach integracji MQTT. Home Assistant domyślnie publikuje w temacie homeassistant/status wiadomość online po uruchomieniu („birth message”) i offline jako ostatnią wolę („last will”). Urządzenia, które subskrybują ten temat, mogą wtedy ponownie wysłać swoją konfigurację, gdy Home Assistant wróci, i nie muszą polegać tylko na wiadomościach zachowanych przez brokera.

Zachowane wiadomości wykrywania przetrwają ponowne uruchomienie brokera i szybko przywracają encje, ale potrafią też tworzyć „duchy”: urządzenia już nie ma, a nikt nie usunął zachowanej wiadomości. Jeśli oprogramowanie urządzenia na to pozwala, lepiej niech wysyła konfigurację ponownie po wiadomości online.

Sprawdź, czy wiadomości dochodzą

Z interfejsu Home Assistanta:

  1. Wejdź w Ustawienia > Urządzenia i usługi, otwórz integrację MQTT i wybierz Konfiguruj (Configure).
  2. W sekcji Opublikuj pakiet (Publish a packet) wpisz temat, na przykład homeassistant/switch/1/power, i treść ON, a potem opublikuj wiadomość.
  3. W sekcji Nasłuchuj tematu (Listen to a topic) wpisz # (wszystkie tematy) albo węższy filtr, na przykład homeassistant/switch/#, i zacznij nasłuchiwać. Wiadomość testowa powinna się pojawić razem z poziomem QoS i flagą „retain”.

Z wiersza poleceń, jeśli masz zainstalowane narzędzia klienckie Mosquitto:

mosquitto_pub -h 127.0.0.1 -t homeassistant/switch/1/on -m "Switch is ON"
mosquitto_sub -h 127.0.0.1 -v -t "homeassistant/#"

Podaj prawdziwą nazwę hosta albo adres IP brokera i dodaj -u oraz -P, jeśli broker wymaga logowania (oficjalna aplikacja wymaga).

Skonfiguruj połączenie w urządzeniach

Każde urządzenie potrzebuje czterech informacji:

  • Adres: nazwa hosta albo adres IP komputera z Home Assistantem w sieci lokalnej (z innego urządzenia nie łączysz się przez 127.0.0.1)
  • Port: 1883 dla zwykłego MQTT albo 8883, jeśli włączyłeś TLS
  • Nazwa użytkownika i hasło: utworzone wcześniej konto Home Assistanta albo lokalne konto brokera
  • Opcjonalnie identyfikator klienta, niepowtarzalny w obrębie brokera

W Zigbee2MQTT wpisujesz to w sekcji mqtt. W ESPHome, jeśli nie korzystasz z natywnego API, użyj komponentu mqtt: z tymi samymi polami. W Tasmocie ustawisz to w menu konfiguracji MQTT. Gdy urządzenie się połączy, wykrywanie (jeśli oprogramowanie je obsługuje) powinno utworzyć encje bez dodatkowego YAML.

Listy kontroli dostępu

Jeśli wszystkie urządzenia logują się na jedno konto, nawet z silnym hasłem, jedno przejęte urządzenie może publikować w dowolnym temacie. Listy kontroli dostępu (ACL) w Mosquitto pozwalają ograniczyć każde konto do wybranych tematów. Dokumentacja aplikacji podaje taki sposób:

  1. Ustaw customize.active na true i customize.folder na mosquitto.
  2. W folderze /share/mosquitto/ umieść plik acl.conf, który wskazuje plik z listą kontroli dostępu.
  3. Na liście nadaj kontom homeassistant i addons uprawnienie readwrite do #. Home Assistant zakłada, że oba mają pełny dostęp, a ograniczenie ich psuje integrację i inne aplikacje.
  4. Dodaj własne konta z węższymi uprawnieniami do tematów.

Do folderu /share dostaniesz się przez Sambę albo bezpośrednio na komputerze, w /usr/share/hassio/share.

Gdy połączenie nie działa

  • Błędy certyfikatu SSL, na przykład CERTIFICATE_VERIFY_FAILED: w ustawieniach brokera MQTT otwórz Inne ustawienia (Other settings) i przy certyfikacie z publicznie zaufanego urzędu ustaw sprawdzanie certyfikatu na Automatycznie (Auto). Jeśli masz własny urząd certyfikacji, wgraj jego certyfikat w opcji Niestandardowy (Custom).
  • Błędy protokołu: sprawdź, czy broker obsługuje MQTT 5.
  • Po ponownym uruchomieniu brakuje wykrytych encji: urządzenie musi ponownie wysłać konfigurację po wiadomości online albo broker musi mieć zachowaną wiadomość konfiguracji. Encje bez unique_id nie wrócą po uruchomieniu, dopóki nie przyjdzie nowa wiadomość wykrywania.
  • Stara konfiguracja brokera w sekcji mqtt: w YAML gryzie się z ustawieniami w interfejsie: usuń ją z YAML, usuń starą integrację, uruchom ponownie Home Assistanta i pozwól mu na nowo wykryć aplikację Mosquitto.