Tutorial mqtt.js, czyli klient MQTT w Javascript - jak podłączyć przeglądarkę do Home Assistant

Przedstawię tutaj jak można łatwo nawiązać połączenie z brokerem MQTT z poziomu przeglądarki internetowej. Wykorzystam do tego gotową bibliotekę MQTT łączącą się z brokerem poprzez mechanizm WebSocket i zademonstruję, jak można jej użyć do odbierania i wysyłania danych poprzez Mosquitto zainstalowany razem z Home Assistant.

UWAGA: Ta prezentacja dotyczy skryptów JS uruchamianych po stronie klienta, czyli w samej przeglądarce. Nie potrzeba tu Node.js ani żadnych podobnych mechanizmów. Wystarczy plik HTML luzem uruchomiony bez żadnego serwera, zadziała to nawet ze statycznym hostingiem takim jak GH Pages od GitHub.
Przeglądarki internetowe nie dają możliwości bezpośredniego nawiązania połączenia po TCP, więc MQTT.js korzysta z mechanizmu tzw. WebSocket. Na szczęście Mosquitto z HA używany do prezentacji też wspiera WebSockety, choć może pojawić się potrzeba konfiguracji tego w mosquitto.conf.

UWAGA - pełny kod jest w załączniku!

Przygodę zaczynamy w kodzie HTML - można tu sobie pomagać narzędziami AI, tak by szybko całość złożyć w oparciu o gotowe style CSS, przykładowo z Bootstrapa. Nas interesuje jednak sam MQTT. Załączamy najpierw bibliotekę:

Trzeba tu będzie podać namiary na nasz serwer MQTT - razem z użytkownikiem i hasłem. Należy pamiętać, że wszystko będzie widoczne w źródle strony dla klienta, więc to podejście nie sprawdzi się w niektórych sytuacjach, ale tu nie uznaję tego za problem. Po prostu dałem użytkownikowi pole na wpisanie własnych informacji:

Teraz trzeba obsłużyć przycisk "Connect", czyli nawiązać połączenie. Całość sprowadza się do pobrania danych z obiektów DOM w momencie kliknięcia:

Link tworzony jest z prefixem ws, czyli standard WebSocket. Jako argumenty podawana jest nazwa użytkownika i hasło. Po rozpoczęciu łączenia (funkcja connect nie jest blokująca) można ustawić callbacki obsługujące różne zdarzenia MQTT. Oto przykładowa implementacja dla demonstracyjnej strony:

Zostają jeszcze dwie operacje, których nie można zrobić poprzez callbacki. Najpierw subskrypcja dla danego tematu (rozpoczęcie nasłuchiwania):

Potem publikowanie danych na wybranym temacie:

To w zasadzie wszystko z implementacji.

Teraz pora na demonstracje.
Najpierw połączenie - po podaniu poprawnych danych powinno się wszystko udać za pierwszym razem. Nic nie musiałem konfigurować w HA, wsparcie WebSocketów miałem już tam włączone. Po prostu podałem port o jeden większy niż ten, który służy do MQTT przez TCP.

Teraz można sprawdzić, czy nasza witryna widzi to, co opublikuje Home Assistant:


Potem pozostaje test w drugą stronę - witryna publikuje, HA odbiera:



Podsumowując, wsparcie standardu WebSocket w MQTT pozwala nam na podłączenie się do brokera z poziomu przeglądarki. Uzyskujemy w ten sposób pełnoprawną komunikację, włącznie z możliwości nasłuchiwania i publikacji danych. Wykonywanie skryptów po stronie serwera jest wtedy zbędne - wystarczy statyczny hosting HTML.
Pokazany tu przykład można by rozwinąć i zrobić z niego pełen kontroler przykładowych urządzeń, ale to innym razem.
Czy widzicie zastosowanie dla połączenia MQTT nawiązanego z poziomu przeglądarki (klienta)?

Pełen program demonstracyjny w załączniku - nie potrzeba serwera, można pobrać plik HTML i uruchomić go luzem z dysku, albo umieścić na jakimś statycznym hostingu.