Zastanawiasz się, jak połączyć różne systemy automatyki domowej? Poznaj REST API i MQTT – dwa fundamenty nowoczesnego Smart Home. W tym poradniku od podstaw, prostym językiem wyjaśniam, jak integrować urządzenia takie jak system FOX z Home Assistant, lub Node-RED używając otwartych standardów komunikacji.
Bez wchodzenia w programowanie, z naciskiem na zrozumienie zasad działania i unikanie typowych błędów już na etapie pierwszych integracji.
Dlaczego w ogóle potrzebujesz REST API i MQTT w swoim domu?
Planując instalację smart home lub jej rozbudowę, warto już na etapie wyboru urządzeń sprawdzić, czy oferują one integrację z Home Assistant, obsługę MQTT lub dostęp przez REST API. To właśnie te elementy decydują o elastyczności systemu i możliwości jego dalszego rozwoju, albo o zamknięciu w ekosystemie jednego producenta. Korzyści wynikające z integracji dobrze widać na przykładzie Home Assistanta, który pełni rolę centralnego punktu zarządzania. Dzięki MQTT i REST API nawet urządzenia bez oficjalnej integracji z Home Assistant (np. FOX) mogą stać się pełnoprawną częścią automatyki, przekazując dane w czasie rzeczywistym lub udostępniając je na żądanie, np. do analizy zużycia energii lub sterowania odbiornikami.
Użytkownik korzysta z jednego interfejsu i jednej automatyki, niezależnie od producenta poszczególnych urządzeń. Trzeba jednak pamiętać, że takie otwarte i elastyczne podejście ma również swoje ograniczenia i pułapki, szczególnie dla osób rozpoczynających pracę ze smart home. W dalszej części poradnika pokażę, na co zwrócić uwagę i jak uniknąć najczęstszych problemów.
Spis treści
- REST API i MQTT, co to właściwie jest i dlaczego elektrycy się z tym spotykają
- Jak wygląda komunikacja w smart home, urządzenie, protokół i system nadrzędny?
- Od czego zacząć przygodę z Home Assistant i Node‑RED?
- Co to jest FOX?
- Jak odczytać dane i sterować urządzeniami smart, gdy nie ma gotowej integracji?
- REST API w systemie FOX, przejście od teorii do praktyki
- Jak połączyć urządzenia FOX z Home Assistantem przy użyciu REST API
- REST API jako pierwszy krok do integracji Smart Home – podsumowanie
- Poznajmy się autorami artykułu są
REST API i MQTT, co to właściwie jest i dlaczego elektrycy się z tym spotykają
REST API i MQTT często pojawiają się w opisach urządzeń smart i dokumentacjach systemów automatyki, ale dla elektryków i majsterkowiczów bywają postrzegane jako „dziwne skróty”, które lepiej ominąć, zamiast zrozumieć. Problem w tym, że właśnie te mechanizmy decydują o tym, czy urządzenia da się ze sobą połączyć i sensownie wykorzystać w jednym systemie.
W praktyce oznacza to, dzięki MQTT lub REST API, smart urządzenia mogą przekazywać dane do systemów nadrzędnych, takich jak Home Assistant czy Node‑RED, i reagować na zdarzenia w obrębie całej instalacji.
Co to jest REST API?
REST API można porównać do zapytania o konkretną informację wysyłanego do urządzenia. System nadrzędny pyta urządzenie o aktualny stan, np. napięcie, moc albo zużycie energii, a urządzenie zwraca odpowiedź. Taki sposób komunikacji dobrze sprawdza się tam, gdzie dane nie muszą być przesyłane cały czas, tylko wtedy, gdy są potrzebne do analizy, sterowania lub wizualizacji.
Co to jest MQTT?
MQTT działa inaczej i jest bliższe temu, jak myślimy o automatyce. Urządzenie samo wysyła informacje o zmianach, a inne elementy systemu je odbierają. Nie trzeba ciągle odpytywać urządzeń o stan, bo dane pojawiają się wtedy, gdy coś się wydarzy. To dlatego MQTT bardzo dobrze sprawdza się w przypadku czujników, liczników energii, przekaźników i sterowania w czasie rzeczywistym.
Czym jest Home Assistant i do czego służy w smart home?
Home Assistant jest systemem nadrzędnym, który zbiera dane z urządzeń smart i umożliwia tworzenie automatyzacji na podstawie informacji otrzymywanych przez otwarte standardy komunikacji. Z punktu widzenia elektryka Home Assistant:
- jest interfejsem użytkownika, czyli miejscem, gdzie widoczne są stany urządzeń, wykresy zużycia energii i przyciski sterowania.
- Umożliwia tworzenie automatyzacji, np. wyłączanie odbiorników po przekroczeniu określonej mocy lub reagowanie na sygnały z czujników.
- Pozwala integrować urządzenia różnych producentów, o ile udostępniają one dane przez: MQTT, REST API lub inne otwarte standardy.
Jeżeli wybrane urządzenie nie oferuje oficjalnej integracji, system Home Assistant sam z siebie go nie zobaczy. Właśnie w tym miejscu pojawia się znaczenie MQTT i REST API, które pozwalają podłączyć nawet takie urządzenia, które pierwotnie nie były projektowane z myślą o Home Assistant, lub Node-RED, ale oferują REST API, lub posiadają integrację MQTT.
Czym jest Node‑RED i czym różni się od Home Assistant?
Node‑RED to narzędzie do tworzenia logiki automatyki, które działa w zupełnie inny sposób niż Home Assistant. Zamiast gotowych ekranów i formularzy, użytkownik pracuje na schemacie składającym się z połączonych bloków. Każdy blok odpowiada za konkretną funkcję, np. odbiór danych przez MQTT, wysłanie zapytania REST API, sprawdzenie warunku lub wysłanie polecenia sterującego.
Logika budowana jest wizualnie, a przepływ danych widać w czasie rzeczywistym.
Node‑RED może działać jako niezależne centrum automatyki, komunikując się bezpośrednio z urządzeniami przez MQTT lub REST API, oraz sterując instalacją bez udziału Home Assistant.
Jak wygląda komunikacja w smart home, urządzenie, protokół i system nadrzędny?
Na etapie pierwszych integracji wiele problemów wynika nie z błędnej konfiguracji, lecz z braku zrozumienia, jak faktycznie wygląda komunikacja w systemie smart home. W najprostszym ujęciu mamy trzy elementy, pierwszym jest urządzenie smart, np. czujnik, licznik energii, przekaźnik lub inny moduł wykonawczy. Drugi element to sposób komunikacji, najczęściej REST API lub MQTT, a trzeci to system nadrzędny, taki jak np. Home Assistant lub Node‑RED, który podejmuje decyzje i steruje instalacją.
W przypadku REST API system nadrzędny komunikuje się z urządzeniem wyłącznie w momencie wysłania zapytania, zarówno przy odczycie stanu, jak i przy wysyłaniu poleceń sterujących. Ze względu na brak komunikacji zdarzeniowej REST API nie zapewnia deterministycznego czasu reakcji i nie powinno być traktowane jako podstawowy mechanizm automatyki czasu rzeczywistego. Dzięki temu REST API dobrze sprawdza się tam, gdzie komunikacja nie musi odbywać się w sposób ciągły.
W przypadku MQTT urządzenia publikują informacje o zmianach stanu w momencie ich wystąpienia, a system nadrzędny oraz inne elementy instalacji mogą na nie reagować w czasie rzeczywistym, bez konieczności cyklicznego odpytywania.
Home Assistant pełni rolę centralnej aplikacji użytkownika do wizualizacji danych i prostych automatyzacji, natomiast Node‑RED jest narzędziem do budowy niestandardowej logiki, zależności czasowych oraz łączenia danych z wielu źródeł.
Z punktu widzenia elektryka kluczowe jest określenie, gdzie podejmowane są decyzje oraz w jaki sposób dane są wykorzystywane w systemie nadrzędnym. W kolejnych rozdziałach przejdziemy od ogólnej architektury do konkretnych przykładów REST API i MQTT w praktycznych instalacjach.
Od czego zacząć przygodę z Home Assistant i Node‑RED?
Zanim pojawią się automatyzacje i integracje po REST API lub MQTT, system smart home potrzebuje miejsca, w którym będzie działał. W praktyce oznacza to konieczność posiadania domowego serwera, do którego urządzenia smart mogą się stale komunikować.
Wiele osób niepotrzebnie przeraża określenie serwer. Niepotrzebnie bo w rzeczywistości najczęściej jest to:
- mały komputer jednopłytkowy, np. Raspberry Pi,
- energooszczędny mini‑PC,
- starszy komputer stacjonarny,
- dedykowane urządzenie przeznaczone specjalnie pod Home Assistant.
Na tym komputerze (serwerze) instaluje się odpowiednie oprogramowanie (Windows lub Linux), które przejmuje rolę centralnego systemu zarządzania. To właśnie tam działa Home Assistant, Node‑RED lub oba naraz. W kontekście integracji za pomocą REST API lub MQTT należy pamiętać, że urządzenia smart nie komunikują się ze sobą bezpośrednio, lecz wysyłają dane do serwera, który decyduje o dalszym działaniu instalacji.
Serwer musi mieć:
- stabilne zasilanie (warto podłączyć go pod odpowiednio dobrany UPS),
- dostęp do tej samej domowej lub biurowej sieci „internetowej” co urządzenia smart, dzięki czemu serwer może się z nimi komunikować i sterować ich pracą,
- możliwość stabilnej komunikacji z urządzeniami smart w domu (połączenia przewodowe lub bezprzewodowe),
- poprawnie skonfigurowane oprogramowanie.
W większości przypadków uruchomienie systemu sprowadza się do zastosowania gotowego środowiska i jego podstawowej konfiguracji (w wielu przypadkach można to zlecić lokalnemu informatykowi). Dopiero po poprawnym skonfigurowaniu serwera możliwe jest dodawanie urządzeń, integracji oraz budowanie automatyki opartej o REST API, MQTT lub Node‑RED.
Aby lepiej omówić komunikację z pomocą REST API i MQTT w dalszej części poradnika będę omawiał zagadnienie na przykładzie sterownika FOX, dlatego krótko wyjaśnię:
Co to jest FOX?
FOX to grupa urządzeń typu smart produkcji F&F, tworzących system zdalnego sterowania i monitoringu oparty o sieć Wi‑Fi, umożliwiający sterowanie odbiornikami, odczyt stanów urządzeń oraz monitoring zużycia energii z poziomu jednej aplikacji.
Podstawą systemu są moduły FOX, takie jak przekaźniki, ściemniacze, sterowniki rolet czy monitory energii, które po podłączeniu do sieci lokalnej są dodawane do aplikacji FOX i automatycznie zaczynają ze sobą współpracować. W typowej instalacji wystarczy poprawne podłączenie elektryczne, dostęp do sieci Wi‑Fi oraz podstawowa konfiguracja w aplikacji.
Istotną cechą systemu FOX jest lokalna komunikacja urządzeń, bez konieczności tworzenia własnego serwera czy skomplikowanej logiki automatyki.
FOX został jednak zaprojektowany w taki sposób, aby nie zamykać użytkownika wyłącznie w jednej aplikacji. Jeżeli funkcje dostępne w aplikacji FOX okazują się niewystarczające, np. gdy potrzebna jest integracja z: Home Assistantem, Node‑RED, zewnętrzna analiza danych lub realizacja niestandardowych automatyzacji, można skorzystać z lokalnych interfejsów REST API oraz protokołu MQTT, które posiadają wszystkie urządzenia FOX.
Dzięki temu FOX może działać zarówno jako:
- prosty i gotowy system sterowania dla użytkownika,
- element większej, otwartej instalacji smart home, integrowanej z systemami i urządzeniami innych producentów.
W dalszej części poradnika na praktycznym przykładzie monitora zużycia energii FOX ENERGY‑1 pokażę, jak wygląda komunikacja lokalna, jakie są różnice pomiędzy REST API i MQTT oraz w jakich zastosowaniach każdy z tych mechanizmów sprawdza się najlepiej. Następnie krok po kroku omówię integrację ENERGY‑1 z Home Assistantem przy użyciu REST API i MQTT, ze wskazaniem typowych błędów projektowych.
Jak odczytać dane i sterować urządzeniami smart, gdy nie ma gotowej integracji?
Co to jest API?
API, czyli Interfejs Programowania Aplikacji, to zestaw jasno określonych reguł komunikacji, który pozwala jednemu programowi lub urządzeniu pobierać dane z innego systemu albo wysyłać do niego polecenia. Można to traktować jako umowę: producent wskazuje, jakie dane są dostępne i jakie funkcje można wywołać, bez ujawniania wewnętrznej logiki działania urządzenia.
Z punktu widzenia elektryka lub instalatora smart home oznacza to bardzo prostą rzecz. Jeżeli urządzenie udostępnia API, to dokładnie wiemy, co da się z niego odczytać oraz czym można sterować. Nie interesuje nas sposób działania elektroniki czy oprogramowania wewnętrznego, interesuje nas tylko zakres dostępnych danych i komend.
Jaka jest różnica pomiędzy API, a REST API?
REST API to jeden z najczęściej stosowanych sposobów projektowania interfejsu API. Opiera się na architekturze REST, czyli zasadach wymiany danych w systemach rozproszonych, gdzie poszczególne elementy instalacji działają na oddzielnych urządzeniach i komunikują się przez sieć lokalną, np. po Ethernet lub Wi‑Fi.
W praktyce REST API w smart home działa w sposób jednoznaczny. System nadrzędny, taki jak Home Assistant lub Node‑RED, wysyła zapytanie o konkretną informację, np. aktualny pobór mocy, napięcie, stan przekaźnika lub wartość energii. Urządzenie odpowiada danymi w ustandaryzowanej postaci, najczęściej w formacie JSON. W przypadku sterowania mechanizm jest identyczny, system wysyła zapytanie zawierające polecenie, np. włączenie wyjścia, zmianę parametru lub wykonanie resetu.
Kluczową cechą REST API jest to, że komunikacja odbywa się wyłącznie na żądanie. Urządzenie samo z siebie, nie wysyła żadnych informacji, dopóki nie zostanie o to zapytane. Takie podejście dobrze sprawdza się przy okresowym odczycie danych, wizualizacji, raportach, analizie zużycia energii oraz sterowaniu wykonywanym w określonych momentach.
REST API jest popularne, ponieważ bazuje na standardowych mechanizmach sieciowych i jest stosunkowo łatwe do wdrożenia przez producentów smart urządzeń. Trzeba jednak mieć świadomość jego ograniczeń. Zbyt częste odpytywanie urządzeń może powodować opóźnienia, zwiększony ruch w sieci oraz obciążenie systemu nadrzędnego np. Home Assistant. Dlatego REST API najlepiej traktować jako narzędzie do odczytu stanu i sterowania wtedy, gdy jest to potrzebne, a nie jako podstawę automatyki wymagającej natychmiastowej reakcji.
Zasady, jakie powinien spełniać system zgodny z architekturą REST, są jasno zdefiniowane i dobrze opisane w dokumentacji technicznej, między innymi na stronie restfulapi.net. W kolejnych częściach poradnika pokażę, jak te założenia wyglądają w praktyce i gdzie REST API jest nieprawidłowo używane w instalacjach smart home.
Jeśli uważnie czytasz, zapewne zwróciłeś uwagę na określenie: JSON.
Co to jest JSON?
JSON (JavaScript Object Notation) to prosty, tekstowy sposób zapisu danych, który jest czytelny zarówno dla systemów informatycznych, jak i dla człowieka. Informacje zapisywane są w postaci par „nazwa – wartość”, np. aktualna moc, napięcie lub stan przekaźnika. Dzięki temu system nadrzędny np. Node-RED dokładnie wie, jaką informację otrzymał i do czego może ją wykorzystać w automatyce, wizualizacji lub dalszej analizie.
Z punktu widzenia elektryka istotne jest to, że JSON nie wymaga żadnej wiedzy programistycznej. Wystarczy zrozumieć, że jest to uporządkowany opis aktualnego stanu urządzenia, który REST API zwraca w odpowiedzi na zapytanie. W kolejnych częściach poradnika pokażę przykładowe dane w formacie JSON i wyjaśnię, jak je interpretować w praktycznych integracjach smart home.
Model komunikacji REST API i jego ograniczenia
W REST API komunikacja odbywa się w modelu klient–serwer. System nadrzędny, czyli klient, wysyła zapytanie do urządzenia, a to zwraca jednorazową odpowiedź. Każde zapytanie jest niezależne i serwer nie przechowuje informacji o wcześniejszych poleceniach ani stanie komunikacji.
W praktyce oznacza to, że przy każdym odczycie lub sterowaniu nawiązywane jest nowe połączenie, wysyłany jest nagłówek zapytania, a po otrzymaniu odpowiedzi połączenie zostaje zamknięte. Przy niewielkiej liczbie urządzeń i rzadkich odczytach nie ma to znaczenia, jednak przy dużej ilości zapytań lub krótkich interwałach odświeżania może prowadzić do:
- zwiększonego ruchu w sieci lokalnej,
- opóźnień w reakcji systemu,
- dodatkowego obciążenia procesora urządzeń i serwera.
Z tego powodu REST API dobrze sprawdza się do okresowego pobierania danych i sterowania na żądanie, ale nie jest optymalnym rozwiązaniem do ciągłej, szybkiej wymiany informacji w czasie rzeczywistym. Uproszczony schemat komunikacji REST przedstawiono na poniższej grafice.
Metody HTTP w REST API i ich praktyczne wykorzystanie
REST API opiera się na standardowych metodach protokołu HTTP, które określają typ wykonywanej operacji na zasobie:
- GET – pobranie danych lub wywołanie operacji,
- POST – wysłanie danych lub utworzenie nowego zasobu,
- PUT – aktualizacja istniejącego zasobu,
- DELETE – usunięcie zasobu.
W klasycznym podejściu REST metoda GET powinna służyć wyłącznie do odczytu danych i nie zmieniać stanu urządzenia. W praktycznych implementacjach IoT zasada ta bywa jednak przez producentów upraszczana. Przykładem takiego uproszczenia komunikacji są np. urządzenia FOX, które w komunikacji wykorzystują wyłącznie metodę GET, zarówno do odczytu parametrów, jak i do wywoływania funkcji sterujących, takich jak załączanie przekaźników, sterowanie roletami czy ściemniaczami. W FOX-ie polecenia sterujące przekazywane są metodą GET w postaci odpowiednich parametrów zapytania.
Takie podejście nie jest zgodne z restrykcyjną definicją REST, ale jest powszechnie stosowane w systemach smart home. Z punktu widzenia integracji najważniejsze jest to, że komunikacja pozostaje prosta, czytelna i możliwa do łatwego wykorzystania w systemach takich jak Home Assistant czy Node‑RED.
Dlaczego REST API musi być zabezpieczone kluczem?
Ponieważ REST API umożliwia bezpośrednią komunikację z urządzeniem po sieci lokalnej, konieczne jest jego odpowiednie zabezpieczenie przed nieautoryzowanym dostępem. W tym celu stosowane są klucze API, które pełnią rolę prostego mechanizmu uwierzytelniania zapytań.
W systemie FOX dostępne są trzy tryby zabezpieczenia REST API, różniące się poziomem bezpieczeństwa:
- klucz stały – urządzenie generuje jeden, niezmienny ciąg znaków, który musi być dołączony do każdego zapytania. Jest to prosta i wystarczająca forma zabezpieczenia w instalacjach lokalnych, pod warunkiem że klucz nie zostanie ujawniony.
- Klucz dynamiczny – klucz generowany jest w sposób zmienny, zgodnie z określonym algorytmem. Zapewnia najwyższy poziom bezpieczeństwa i najlepiej sprawdza się w instalacjach, gdzie REST API wykorzystywane jest intensywnie lub w środowiskach o podwyższonych wymaganiach.
- Klucz niewymagany – tryb testowy, w którym API pozostaje otwarte i reaguje na zapytania bez weryfikacji tożsamości. Ułatwia pierwsze testy i diagnostykę, jednak nie powinien być stosowany w docelowej instalacji, szczególnie tam, gdzie REST API wykorzystywane jest również do sterowania urządzeniami wykonawczymi (np. otwieraniem bram, rolet).
W praktyce klucz API jest jedyną barierą chroniącą urządzenia przed nieautoryzowanym sterowaniem. Dlatego po zakończeniu testów należy zawsze przełączyć REST API na tryb z kluczem lub całkowicie je wyłączyć, jeśli nie jest wykorzystywane.
Jak wygląda poprawne zapytanie REST API do urządzenia smart?
Zanim przejdziemy do praktycznej integracji smart urządzeń, warto zrozumieć, jak zbudowane jest zapytanie REST API. Poprawna składnia zapytania decyduje o tym, czy urządzenie zwróci dane lub wykona określoną akcję.
Zapytanie REST API np. do urządzenia FOX składa się z kilku podstawowych elementów, co pokazano na poniższym schemacie:
- metody HTTP, w tym przypadku GET,
- adresu IP urządzenia w sieci lokalnej (aby zapytania działały poprawnie, urządzenie powinno mieć w routerze przypisany stały adres IP),
- opcjonalnie klucz API (jeśli jest aktywny),
- ścieżki wywołania, wskazującej konkretną funkcję.
Przykładowe zapytanie ma postać:
- GET http://192.168.0.127/0000/get_current_parameters
Dostępne wywołania REST API zależą od konkretnego modelu urządzenia i w omawianym przypadku są opisane w dokumentacji F&F, dostępnej pod adresem: http://fox-updater.fhome.pl/rest_api_doc/
Dla monitora zużycia energii FOX ENERGY‑1 dostępne są następujące wywołania:
- /0000/get_total_energy – zwraca dane dotyczące zużycia energii,
- /0000/get_current_parameters – zwraca aktualne parametry sieci, takie jak napięcie czy moc.
Zrozumienie składni zapytania REST API pozwala świadomie interpretować otrzymywane dane i jest kluczowe przy dalszej integracji z Home Assistantem, Node‑RED lub własnymi skryptami.
REST API w systemie FOX, przejście od teorii do praktyki
1. Konfiguracja sieciowa przed uruchomieniem REST API
Skoro wiemy już, czym jest i jak działa REST API, możemy przejść do jego zastosowania w praktyce na przykładzie systemu FOX. W roli serwera może działać dowolny komputer w tej samej sieci lokalnej, w moim przypadku jest to laptop z systemem Linux Ubuntu. W docelowych instalacjach smart home najczęściej będzie to jednak dedykowane urządzenie o niskim poborze mocy, np. mikrokomputer Raspberry Pi, mini‑PC lub serwer Home Assistant.
Zanim przejdziemy do konfiguracji REST API w samym urządzeniu, konieczne jest przygotowanie sieci lokalnej. Nawet poprawnie skonfigurowane API nie zadziała stabilnie, jeżeli podstawowe ustawienia sieciowe będą błędne.
Rezerwacja i przypisanie stałego adresu IP
Domyślnie większość routerów przydziela dynamicznie adresy IP za pomocą DHCP. Przy dynamicznym DHCP adres IP urządzenia nie jest gwarantowany, dlatego po restarcie routera lub wygaśnięciu dzierżawy może on ulec zmianie, a zapytania REST API przestaną działać.
Dlatego urządzenie FOX powinno mieć w routerze przypisany stały adres IP, powiązany z jego adresem MAC. W zależności od producenta routera opcja ta może różnie się nazywać. W moim przypadku (TP‑LINK) jest to rezerwacja adresów w sekcji Serwer DHCP.
Wyłączenie izolacji punktów dostępowych (AP isolation)
W niektórych sieciach, szczególnie gościnnych lub publicznych, włączona jest funkcja izolacji punktów dostępowych. Uniemożliwia ona komunikację pomiędzy urządzeniami w tej samej sieci. Przy aktywnej izolacji zapytania REST API, mimo poprawnych adresów IP, nie będą docierać np. do modułów FOX.
Weryfikacja podsieci
Serwer, z którego wysyłane są zapytania REST API, oraz urządzenie FOX muszą znajdować się w tej samej podsieci IP. W przeciwnym razie komunikacja lokalna nie będzie możliwa bez dodatkowej konfiguracji routingu, co nie ma większego sensu w typowej instalacji smart home.
2. Konfiguracja REST API w aplikacji FOX
Po przygotowaniu sieci lokalnej możemy przejść do konfiguracji REST API bezpośrednio w aplikacji mobilnej FOX. Na tym etapie warto zacząć od sprawdzenia, czy urządzenie posiada poprawny adres IP, zgodny z rezerwacją wykonaną w routerze. Adres IP widoczny jest na dole ustawień zaawansowanych urządzenia.
Następnie, pozostając w ustawieniach zaawansowanych, należy rozwinąć sekcję Integracje. Znajduje się tam pozycja REST API z polem Tryb REST API, domyślnie ustawionym jako Nieaktywne. Po jej rozwinięciu dostępny jest wybór trybu zabezpieczenia API. Na potrzeby pierwszych testów można tymczasowo wybrać opcję Klucz niewymagany, a następnie zatwierdzić ustawienia.
Po aktywowaniu REST API urządzenie powinno być dostępne do komunikacji w sieci lokalnej. Do testów wykorzystuję komendę „curl”, uruchamiane w terminalu systemu Linux lub wierszu poleceń (CMD / PowerShell) w systemie Windows. Otrzymanie poprawnej odpowiedzi z smart urządzenia potwierdza, że komunikacja po REST API działa prawidłowo.
Przypominam, że tryb bez klucza jest wygodny na etapie testów, jednak nie powinien być stosowany w gotowej instalacji. Dlatego kolejnym krokiem jest zmiana trybu zabezpieczenia REST API. Do wyboru mamy dwie metody uwierzytelniania: klucz stały oraz klucz dynamiczny. W moim przypadku wybrałem klucz stały. Po jego aktywacji aplikacja generuje unikalny klucz, który będzie wymagany przy każdym zapytaniu.
Od tego momentu każde zapytanie do urządzenia musi zawierać poprawny klucz API. Zapytanie z prawidłowym kluczem zostanie obsłużone poprawnie, natomiast użycie błędnego klucza spowoduje odrzucenie żądania przez urządzenie.
| Zapytanie – poprawny klucz | Zapytanie – błędny klucz |
 |
 |
Ten etap kończy podstawową konfigurację REST API w systemie FOX i przygotowuje urządzenie do dalszej integracji, np. z Home Assistantem lub własnymi skryptami.
3. Praktyczne zastosowanie REST API poza Home Assistantem
Skoro wiemy już, że komunikacja z urządzeniem FOX po REST API działa poprawnie, warto pokazać, jak można wykorzystać ją w praktyce poza gotowymi systemami typu Home Assistant. Jednym z prostszych i jednocześnie bardzo elastycznych podejść jest użycie własnego skryptu działającego na komputerze lub lokalnym serwerze.
Poniżej przedstawiony jest fragment przykładowego klienta napisanego w języku Python, który cyklicznie pobiera dane z monitora energii FOX ENERGY‑1 i realizuje dwa proste warunki logiczne:
- brak załączonego obciążenia,
- przekroczenie zdefiniowanej progowej wartości napięcia.
Odczyt danych jest możliwy bez dodatkowego parsowania, ponieważ odpowiedź z REST API urządzenia FOX zwracana jest w formacie JSON, co znacząco ułatwia dalsze przetwarzanie wartości w skrypcie.
Dla ułatwienia poniżej podaję kod źródłowy przykładowego klienta, który można skopiować i wykorzystać jako punkt wyjścia do własnych testów oraz automatyzacji:
import asyncio
import aiohttp
from datetime import datetime
async def main():
# Konfiguracja
ENERGY1_IP = '192.168.0.127'
ENERGY1_API_KEY = 'e2d6f62580491cc32fe9cf4d9e'
# Wywolania
ENERGY1_PARAMS = f"http://{ENERGY1_IP}/{ENERGY1_API_KEY}/get_current_parameters"
ENERGY1_ENERGY = f"http://{ENERGY1_IP}/{ENERGY1_API_KEY}/get_total_energy"
print(f"Rozpoczynam monitorowanie ENERGY1 ({ENERGY1_IP}) co 10 sekund:")
print("Nacisnij Ctrl+C, aby zatrzymac.")
async with aiohttp.ClientSession() as session:
while True:
try:
async with session.get(ENERGY1_PARAMS) as response:
if response.status == 200:
data = await response.json()
# Pobranie wartości napięcia
voltage = data.get('voltage', 0)
power_active = data.get('power_active', 0)
# Pobieranie aktualnego czasu dla lepszej czytelności logów
now = datetime.now().strftime("%H:%M:%S")
# Odczyt pomiaru mocy czynnej
print(f"[{now}] Moc czynna: {power_active}W")
# Przykladowy warunek 1 - brak zalaczonego obciazenia
if float(power_active) == 0.0:
print(f"[{now}] INFO: Nie zalaczono obciazenia.")
#
# Miejsce na dodatkowa logike
#
# Przykladowy warunek 2 - przekroczenie progowej wartosci napiecia
VOLTAGE_THRESHHOLD = 250.0
if float(voltage) > VOLTAGE_THRESHHOLD:
print(f"[{now}] INFO: Przekroczono progowa wartosc napiecia.")
#
# Miejsce na dodatkowa logike, np. zalacz urzadzenie
#
else:
print(f"[{now}] Napiecie: {voltage}V")
else:
print(f"Blad HTTP {response.status}")
except Exception as e:
print(f"Blad polaczenia: {e}")
# Sprawdzaj co 10 sekund
await asyncio.sleep(10)
if __name__ == '__main__':
try:
asyncio.run(main())
except KeyboardInterrupt:
print("Przerwanie przez uzytkownika.")
Analogiczne, wykorzystując odpowiednie wywołania REST API, można je zastosować również dla pozostałych modułów systemu FOX, takich jak przekaźniki, sterowniki rolet czy ściemniacze. W praktyce oznacza to, że od momentu „wystawienia” urządzenia do własnego skryptu, możliwości automatyzacji przestają być ograniczone funkcjami aplikacji mobilnej dostarczonej przez producenta smart urządzenia.
Takie rozwiązanie otwiera także drogę do łączenia np. systemu FOX z urządzeniami i usługami innych producentów, o ile udostępniają one własne API. Przykładowe scenariusze obejmują sterowanie odbiornikami w oparciu o prognozę pogody, analizę cen energii z giełdy (np. giełda energii elektrycznej) lub łączenie danych z kilku niezależnych systemów.
Istotną zaletą takiego podejścia jest to, że cała logika systemu działa lokalnie, na własnym komputerze lub serwerze. Oznacza to, że nawet w przypadku awarii łącza internetowego automatyki wykonywane lokalnie, takie jak załączenie oświetlenia z przycisku czy sterowanie po wykryciu ruchu, funkcjonują bez zakłóceń. Niedostępne są jedynie dane pobierane na bieżąco z internetu, na przykład prognoza pogody czy informacje z giełdy, natomiast podstawowe funkcje instalacji pozostają w pełni sprawne.
Takie rozwiązanie eliminuje zależność od zewnętrznych serwerów producenta oraz od ciągłego dostępu do internetu. Zapewnia pełną kontrolę nad danymi, sposobem ich przetwarzania oraz nad logiką sterowania instalacją, co ma kluczowe znaczenie zarówno dla niezawodności, jak i bezpieczeństwa systemu.
Jak połączyć urządzenia FOX z Home Assistantem przy użyciu REST API
Urządzenia FOX nie posiadają oficjalnej integracji z Home Assistantem opartej na REST API. W praktyce znacznie lepiej sprawdza się w tym celu MQTT, o czym będzie mowa w dalszej części artykułu. Mimo to, możliwa jest integracja np. monitora energii FOX ENERGY‑1 z Home Assistantem z wykorzystaniem REST API i w tym rozdziale pokażę, jak to zrobić w sposób poprawny.
Zakładam, że serwer Home Assistant jest już uruchomiony i działa w tej samej sieci lokalnej co urządzenie FOX.
1. Instalacja dodatku File editor
Do edycji plików konfiguracyjnych Home Assistanta potrzebne będzie narzędzie File editor. Dodatek ten można zainstalować z poziomu menu: Ustawienia → Aplikacje → Zainstaluj aplikację → File editor
Po instalacji narzędzie umożliwia bezpośrednią edycję plików konfiguracyjnych w strukturze Home Assistanta.
2. Plik konfiguracyjny configuration.yaml
W pierwszej kolejności tworzymy nowy plik konfiguracyjny o rozszerzeniu .yaml, który będzie zawierał definicję integracji REST API dla np. ENERGY‑1. Ułatwia to zachowanie porządku w konfiguracji i oddzielenie jej od głównego pliku.
W File editorze tworzę nowy plik o nazwie: rest_fox_energy-1.yaml
Następnie otwieramy plik configuration.yaml i dodajemy do niego odwołanie do nowo utworzonego pliku: rest: !include rest_fox_energy-1.yaml
Po zapisaniu zmian Home Assistant będzie ładował konfigurację REST API z osobnego pliku.
3. Pobieranie parametrów z monitora energii rest_fox_energy-1.yaml
Teraz przechodzimy do właściwej konfiguracji REST API w pliku rest_fox_energy-1.yaml. Parametry pobierane z monitora energii deklarujemy jako encje typu Sensor, co pozwala w pełni wykorzystać ich możliwości w Home Assistant.
W tym artykule skupiam się wyłącznie na monitorze energii ENERGY‑1. W przypadku innych urządzeń z rodziny FOX domena encji może być inna, np. Switch, Light lub Cover, zgodnie z dokumentacją Home Assistanta.
Poniżej odnośniki do ich dokumentacji.
- https://www.home-assistant.io/integrations/switch.mqtt/
- https://www.home-assistant.io/integrations/light.mqtt/
- https://www.home-assistant.io/integrations/cover.mqtt/
Fragment przykładowej konfiguracji pokazano poniżej.
Podstawowe elementy konfiguracji sensora:
- resource – ścieżka wywołania REST API (bez metody GET),
- scan_interval – odstęp czasowy odpytywania urządzenia, w sekundach,
- name – nazwa encji widoczna w Home Assistant,
- unique_id – unikalny identyfikator encji,
- value_template – sposób wyciągnięcia konkretnej wartości z odpowiedzi.
Aby poprawnie zdefiniować value_template, należy sprawdzić, w jakiej postaci urządzenie zwraca dane.
Urządzenia FOX zwracają dane w formacie JSON, dlatego w konfiguracji wykorzystywana jest zmienna value_json. Po kropce wskazujemy konkretny parametr, np. voltage lub power_reactive.
-
- unit_of_measurement, device_class – należy zadbać, aby przypisane jednostki i klasy urządzeń były zgodne z wartościami zwracanymi przez REST API. Ma to bezpośredni wpływ na sposób prezentacji danych, wykresy oraz możliwość dalszego przetwarzania ich w Home Assistant. Podsumowując, urządzenie wysyła daną w określonej jednostce, jeśli wstawimy inną jednostkę uzyskamy błędne odczyty. Jednostki można zmienić później, jednak poprawna konfiguracja na tym etapie pozwala uniknąć błędów i konieczności migracji encji.
Lista wspieranych klas sensorów i ich jednostek znajduje się w dokumentacji Home Assistant: https://www.home-assistant.io/integrations/sensor
Podczas definiowania sensora należy zadbać o:
- poprawne jednostki pomiarowe,
- odpowiednią device_class, zgodną z dokumentacją Home Assistanta.
Po dodaniu wszystkich wymaganych parametrów plik należy zapisać.
Kompletny plik rest_fox_energy-1.yaml, zawierający wszystkie dostępne odczyty z monitora energii, może wyglądać następująco:
# ENERGY-1 - CURRENT PARAMETERS
- resource: "http://192.168.0.127/e2d6f62580491cc32fe9cf4d9e/get_current_parameters"
scan_interval: 10 # Odswiezanie co 10 sekund
sensor:
- name: "ENERGY-1 Voltage"
unique_id: ENERGY-1_u
value_template: "{{ value_json.voltage }}"
unit_of_measurement: "V"
device_class: voltage
- name: "ENERGY-1 Current"
unique_id: ENERGY-1_i
value_template: "{{ value_json.current }}"
unit_of_measurement: "A"
device_class: current
- name: "ENERGY-1 Power_active"
unique_id: ENERGY-1_p_a
value_template: "{{ value_json.power_active }}"
unit_of_measurement: "W"
device_class: power
- name: "ENERGY-1 Power_reactive"
unique_id: ENERGY-1_p_r
value_template: "{{ value_json.power_reactive }}"
unit_of_measurement: "var"
device_class: reactive_power
- name: "ENERGY-1 Frequency"
unique_id: ENERGY-1_f
value_template: "{{ value_json.frequency }}"
unit_of_measurement: "Hz"
device_class: frequency
- name: "ENERGY-1 Power_factor"
unique_id: ENERGY-1_cphi
value_template: "{{ value_json.power_factor }}"
device_class: power_factor
#ENERGY-1 - GET TOTAL ENERGY
- resource: "http://192.168.0.127/e2d6f62580491cc32fe9cf4d9e/get_total_energy"
scan_interval: 30 # Calkowite zuzycie energii mozemy aktualizowac rzadziej
sensor:
- name: "ENERGY-1 Active_energy"
unique_id: ENERGY-1_a_e
value_template: "{{ value_json.active_energy }}"
unit_of_measurement: "mWh"
device_class: energy
- name: "ENERGY-1 Reactive_energy"
unique_id: ENERGY-1_r_e
value_template: "{{ value_json.reactive_energy | float / 1000 }}"
unit_of_measurement: "varh"
device_class: reactive_energy
- name: "ENERGY-1 Active_energy_import"
unique_id: ENERGY-1_a_e_imp
value_template: "{{ value_json.active_energy_import }}"
unit_of_measurement: "mWh"
device_class: energy
- name: "ENERGY-1 Reactive_energy_import"
unique_id: ENERGY-1_r_e_imp
value_template: "{{ value_json.reactive_energy_import | float / 1000}}"
unit_of_measurement: "varh"
device_class: reactive_energy
Czy zauważyłeś, że energia czynna jest wyrażana w mWh, natomiast energia bierna w varh? Wynika to ze sposobu obsługi jednostek w klasach energii oraz w polu reactive_energy. Dla klasy energy jednostką może być mWh, natomiast energia bierna musi być wyrażona w varh lub kvarh. Monitor energii FOX wysyła dane w jednostkach mWh oraz mvarh, dlatego konieczne jest programowe przeskalowanie jednostek.
Sprawdzenie poprawności konfiguracji i uruchomienie integracji
Po zakończeniu edycji plików konfiguracyjnych należy upewnić się, że konfiguracja Home Assistanta jest poprawna składniowo. Ten krok pozwala wykryć błędy w plikach YAML jeszcze przed uruchomieniem integracji i zapobiega problemom podczas startu systemu.
Wchodzimy w Ustawienia, następnie Narzędzia deweloperskie, zakładka YAML. Tam wybieramy opcję Sprawdź poprawność konfiguracji. Jeżeli Home Assistant nie zgłosi błędów, wykonujemy restart, aby ponownie uruchomić system i wczytać nowe ustawienia.
W praktyce jest to moment, w którym Home Assistant po raz pierwszy korzysta z przygotowanej konfiguracji REST API lub MQTT i weryfikuje poprawność definicji encji.
Weryfikacja odczytów i dostępnych encji w Home Assistant
Po ponownym uruchomieniu Home Assistanta skonfigurowane parametry powinny pojawić się jako Encje. Każda encja reprezentuje jeden konkretny odczyt lub funkcję urządzenia, np. napięcie, moc, energię lub stan wyjścia.
Klikając wybraną encję, można:
- sprawdzić jej aktualną wartość,
- zmienić sposób reprezentacji danych,
- skorygować jednostki lub klasę urządzenia, jeżeli jest taka potrzeba.
Od tego momentu dane z urządzenia FOX są pełnoprawną częścią systemu Home Assistant. Mogą być wykorzystywane do:
- tworzenia automatyzacji,
- obserwacji przebiegów czasowych,
- budowy scen i reguł logicznych,
- integracji z innymi urządzeniami i systemami smart home.
Jeżeli encje pojawiają się poprawnie i ich wartości aktualizują się w czasie, oznacza to, że komunikacja po REST API działa prawidłowo i system jest gotowy do dalszej pracy.
REST API dobrze sprawdza się do odczytu stanu urządzeń i sporadycznego sterowania, jednak w automatyce smart home bardzo często potrzebujemy reakcji natychmiastowej i komunikacji zdarzeniowej, dlatego w kolejnej części poradnika przejdę do MQTT, protokołu zaprojektowanego właśnie z myślą o takich zastosowaniach.
REST API jako pierwszy krok do integracji Smart Home – podsumowanie
W tej części poradnika skupiłem się na REST API, ponieważ jest to najprostszy i najbardziej naturalny punkt wejścia do integracji urządzeń smart home, szczególnie dla elektryków i majsterkowiczów, którzy nie chcą zaczynać od zaawansowanego programowania ani skomplikowanej infrastruktury.
REST API pozwala w czytelny sposób:
- odczytywać parametry urządzeń smart,
- integrować urządzenia różnych producentów w jednym systemie,
- analizować dane pomiarowe, takie jak zużycie energii, napięcie czy moc,
- realizować proste sterowanie i logikę działania.
Dzięki temu możliwe jest zbudowanie stabilnej, lokalnej instalacji smart home, która działa nawet bez dostępu do internetu i nie jest uzależniona od chmury producenta. Dla wielu zastosowań, takich jak monitoring energii, raportowanie danych, podstawowe sterowanie czy integracja z własnymi skryptami, REST API jest bardzo wygodne i w zupełności wystarczające.
Jednocześnie podczas praktycznych przykładów wyraźnie widać ograniczenia tego podejścia. REST API opiera się na cyklicznym odpytywaniu urządzeń o ich stan, co oznacza, że:
- system nie reaguje natychmiast na każdą zmianę,
- zbyt częste odpytywanie może obciążać sieć i serwer,
- nie jest to optymalny mechanizm do automatyki czasu rzeczywistego.
Właśnie w tym miejscu wielu użytkowników zaczyna zadawać sobie pytanie, czy da się to zrobić lepiej, szybciej i w bardziej „automatyczny” sposób. Gdy w instalacji pojawia się potrzeba natychmiastowej reakcji na zdarzenie, takiej jak zmiana stanu wyjścia, alarm, ruch czy przekroczenie określonych wartości, samo REST API przestaje być wystarczające.
Dlatego w drugiej części poradnika zatytułowanej: Czy MQTT naprawdę daje przewagę w Smart Home – poradnik cz. 2, przechodzę do protokołu MQTT i komunikacji zdarzeniowej. Pokażę, czym w praktyce MQTT różni się od REST API, jak działa publikowanie i subskrypcja danych oraz czy MQTT rzeczywiście daje przewagę w instalacjach smart home. Na konkretnych przykładach z Home Assistantem i urządzeniami FOX zobaczysz, w jakich sytuacjach MQTT upraszcza automatykę, przyspiesza reakcję systemu i pozwala budować instalacje bardziej elastyczne i odporne na rozbudowę.
Jeżeli REST API pozwoliło Ci zrozumieć, jak połączyć urządzenia i odczytać dane, to MQTT pokaże, jak sprawić, aby instalacja zaczęła reagować dokładnie wtedy, gdy powinna.
Poznajmy się autorami artykułu są:
Marcin Osztynowicz – jestem studentem kierunku Automatyka i Robotyka na Politechnice Poznańskiej. W praktyce i w trakcie studiów koncentruje się na szeroko pojętej automatyce przemysłowej, obejmującej sterowniki programowalne PLC, systemy wizyjne oraz rozwiązania z zakresu robotyki. Na co dzień pracuje jako automatyk w branży Water Treatment, gdzie zajmuje się projektowaniem, uruchamianiem i utrzymaniem systemów automatyki procesowej. Łączę wiedzę akademicką z praktyką przemysłową, skupiając się na niezawodności, funkcjonalności i bezpieczeństwie systemów sterowania.
Piotr Bibik – od ponad 30 lat moje życie zawodowe kręci się wokół elektrotechniki. Nie jestem teoretykiem – moją wiedzę budowałem przez ćwierć wieku pracy u jednego z największych dystrybutorów materiałów elektrycznych w Polsce oraz podczas tysięcy godzin spędzonych na instalacjach.
Elektryka to moja pasja, a portal Napięcie Salama to miejsce, gdzie dzielę się bogatym doświadczeniem, które zdobywałem m.in. jako autor setek publikacji eksperckich dla czołowych portali branżowych (np. Łączy Nas Napięcie). Dziś tę wiedzę przekładam na konkretne wsparcie dla moich klientów, dbając o to, by każda instalacja była bezpieczna i nowoczesna.
Wierzę, że o trudnych sprawach można mówić prosto – tak, aby każdy inwestor i instalator mógł podjąć decyzję, która zapewni bezpieczeństwo jego rodzinie i urządzeniom.
W czym mogę Ci pomóc?
-
Dla Inwestorów: Prowadzę konsultacje techniczne, podczas których sprawdzam projekty i podpowiadam rozwiązania, które realnie działają.
-
Dla Instalatorów i Projektantów: Dzielę się doświadczeniem z zakresu nowoczesnej automatyki i systemów zasilania, pomagając unikać kosztownych błędów montażowych.
-
Dla Producentów: Pomagam spojrzeć na produkty oczami praktyka i rzetelnie przekazać ich wartość rynkowi.
Moja zasada jest prosta: instalacja ma być bezpieczna, nowoczesna i zrozumiała dla użytkownika. Jeśli szukasz rzetelnego doradztwa lub chcesz uniknąć awarii, o których piszę na tym blogu – zapraszam do kontaktu.
