Oto pakiet oprogramowania pozwalający zintegrować Exta Life z Home Assistant za pośrednictwem MQTT.
UWAGA: Od dnia 14.11.2019 pojawiła się także możliwość integracji natywnej, bez konieczności używania MQTT - opis w
tym wątku.
Opis rozwiązania / wprowadzenie:Integracja oparta jest o 1 bibliotekę napisaną w Python 3.5 oraz 2 programy także napisane w Pythonie. Programy te za pośrednictwem biblioteki symulują komunikację z EFC-01, jak gdyby komunikowała się z nim aplikacja Exta Life. Zmiany stanów z poziomu Home Assistant odbywają się w czasie rzeczywistym. Reakcja kontrolera jest natychmiastowa - tak jak w aplikacji Exta Life. Natomiast update statusu odbiornika Exta Life jest realizowany za pośrednictwem poolingu stanu domyślnie odbywającego się co 5 minut. Do ich uruchomienia stworzone zostały dodatkowo skrypty shellowe (pliki z rozszerzeniem
.sh). Jeden z programów (
main_ha2exta.py) tworzy połaczenie między kontrolerem EFC-01 a Home Assistant i przekazuje komendy sterowania z HA do EFC-01 na bieżąco. Drugi program (
main_exta2ha.py) służy do cyklicznego odczytywania bieżących stanów wszystkich odbiorników i czujników Exta Life z instalacji, do których użytkownik podany w konfiguracji ma dostęp.
Integracja wykorzystuje mechanizm HA MQTT Discovery co oznacza, że urządzenia Exta Life dodawane są do HA automatycznie przy najbliższym odczycie stanów przez program
main_exta2ha.py. Nie oznacza to jednak, że będą widoczne w GUI HA. To zawsze wymaga ręcznej konfiguracji poprzez edycję plików HA. HA daje pełną dowolność jak i gdzie urządzenia będą wyświetlane - w jakiej zakładce, z jaką ikoną, w jakiej kolejności, z jakimi opcjami itp. dlatego ręczna konfiguracja jest niezbędna.
Automatyzm Discovery oznacza jednak, że urządzenia Exta Life będą automatycznie skonfigurowane dla HA pod kątem komunikacji, możliwości (czy odbiornik typu światło (czy ściemnialny, czy zwykłe włącz, wyłącz), czy roleta, tematy MQTT do komunikacji itp) oraz widoczne w widoku deweloperskim HA w liście encji.
Plik konfiguracyjny:Obydwa programy korzystają z pliku konfiguracyjnego
exta_ha_config.yaml,
niezbędnego do działania całego rozwiązania, który zawiera informacje o tym, jak dane urządzenie Exta Life zostało skonfigurowane w Home Assistant. Jest łącznikiem pomiędzy obydwoma programami, ponieważ obydwa programy muszą wiedzieć jak dane urządzenie Exta Life zostało przypisane do Home Assistant.
Plik jest samoczynnie generowany i aktualizowany przez program
main_exta2ha.py. Plik ma format YAML (
https://yaml.org/). Przed jego edycją silnie polecam zaznajomić się ze składnią YAML, ponieważ wcięcia mają tam znaczenie i nieumiejętna edycja spowoduje błędy w działaniu programu. Zawarte są w tym pliku następujące informacje:
- nazwa encji w Home Assistant zbudowana jako złożenie ID urządzenia(wartość 'device') Exta Life oraz numeru kanału. Przykładowo niech ROP-22 w kontrolerze EFC-01 ma ID (pole 'device') o wartości 1. Powstaną dla niego dwa wpisy w pliku wg reguły [id]-[kanał] czyli odpowiednio 1-1, 1-2. Generalnie w Home Assistant powstanie dla ROP-22 tyle encji, ile kanałów czyli 2. Analogicznie dla odbiorników ROM mogą być 4 kanały więc powstaną 4 osobne encje.
- typ komponentu HA reprezentującego dany kanał urządzenia Exta Life: light, switch, cover, sensor
- tematy MQTT do sterowania urządzeniem przez HA oraz do zwracania stanu urządzenia Exta Life do HA. Aby uniknać nadmiarowości danych to zapisany jest tylko człon główny wszystkich tematów oraz poszczególne końcówki
Przykładowy wpis z pliku:
0-1:
brightness_scale: 100
can_dim: true
can_rgb: false
component: light
name: Punkt 1
on_command_type: brightness
topic_base: homeassistant/light/0-1/
topics:
brightness_command_topic: set_value
brightness_state_topic: state_value
command_topic: switch
config: config
state_topic: state
Wpis taki reprezentuje urządzenie Exta Life o ID 0 i kanale 1 (stąd:
0-1:). Dokładnie rzecz ujmując jest to RDP-21. Zmapowany jest on na komponent HA typu 'light', ponieważ komponent ten pozwala na regulację natężenia oświetlenia (
can_dim: true) oprócz włączania i wyłączania.
Przykładowo temat MQTT do przekazywania stanu odbiornika Exta Life do HA to połączenie wartości pola
topic_base oraz
state_topic - czyli
'homeassistant/light/0-1/state'Jeśli ktoś poczyta dokumentację elementu light komponentu MQTT w HA to zauważy, że wiele z pól tego wpisu odpowiada dokładnie polom konfiguracyjnym komponentu MQTT.
UWAGA: program main_exta2ha.py posiada domyślą logikę mapującą urządzenia Exta Life (ROP, ROM, RDP, SRP, itp) na komponenty HA. Logika ta stworzona została na moje potrzeby. Mam świadomość, że wypadałoby, aby byłą konfigurowalna, ale elastyczność i konfigurowalność niestety zawsze oznacza większy nakład pracy programistycznej, czyli czasu. Do tej pory nie miałem na tyle czasu, aby wprowadzić tutaj konfigurowalność tej logiki.
Oznacza to, że aby dostosować logikę procesu Discovery do swoich potrzeb potrzebna jest zmiana kodu w bibliotece
ExtaLife_HA.py w metodzie
add_entry_from_device klasy HAConfig.
Drugim rozwiązaniem jest dokonanie ręcznych zmian w wygenerowanym pliku i ponowne przesłanie konfiguracji do HA programem
main_exta2ha.sh. O tym jak to zrobić - poniżej w procedurze postępowania.
Ogólna reguła jest taka, że ROP i ROM mapowane są jako switch, chyba, że mają w aplikacji Exta Life przypisane ikony kierunkowego reflektora sufitowego
lub ikonę zwykłej żarówki E27
- wtedy będą zmapowane jako light bez możliwości ściemniania.
Pozostałe komponenty mapowane są wg intuicyjnych reguł - ściemniacz jako light z regulacją, czujniki temperatury jako sensor, SRP/M jako cover.
Obsługiwane urządzenia Exta Life:* Odbiorniki: ROM, ROP, RDM, RDP, SRP, SRM, przygotowane podwaliny po obsługę SLR
* Czujniki: czujnik temperatury z RNK oraz czujniki RCT
Urządzenia Exta Free nie są na razie wspierane. Z racji, że z Exta Free posiadam tylko jeden ROP-01 - mam za mało informacji, aby dodać ich obsługę.
Reprezentacja w Home Assistant jako następujące komponenty:
* MQTT Light -
https://www.home-assistant.io/components/light.mqtt/* MQTT Switch -
https://www.home-assistant.io/components/switch.mqtt/* MQTT Cover -
https://www.home-assistant.io/components/cover.mqtt/* MQTT Sensor -
https://www.home-assistant.io/components/sensor.mqtt/Wymagania - w co się trzeba będzie wyposażyć:
1. Home Assistant - hass.io na Raspberry Pi, ale moim zdaniem nawet lepszym pomysłem jest HA na Dockerze (czyli dyski NAS, inne Linuxy oraz Docker dla Windows ) - pobrać najnowszą wersję stabilną (nie betę)
2. Broker MQTT - polecam Mosquitto - można także w dockerze
3. Python
3.5 lub nowszy do uruchomienia 2 programów integracji Exta Life <-> MQTT w Home Assistant. Na starszej wersji będą błędy składniowe
4. Dodatkowe pakiety w Pythonie (doinstalować przez: pip install): mqtt (paho mqtt), json, yaml, unidecode
Procedura wdrożenia:0. Otworzyć butelkę/puszkę piwa
1. Zainstalować Home Assistant oraz dodać w pliku
configuration.yaml konfigurację dla komponentu MQTT według instrukcji
https://www.home-assistant.io/components/mqtt/ oraz
https://www.home-assistant.io/docs/mqtt/discovery/Ustawić parametr
discovery_prefix na wartość homeassistant, czyli
discovery_prefix: homeassistant2. Przetestować poprawność instalacji i konfiguracji według instrukcji:
https://www.home-assistant.io/docs/mqtt/testing/To będzie wymagało edycji głównego pliku konfiguracyjnego HA -
configuration.yaml i ręcznego dodania testowego, wirtualnego urządzenia MQTT.
Polecam też instalację jakiegoś dobrego klienta MQTT np MQTT.fx i zasubskrybowanie wszystkich wątków do monitorowania przyszłej komunikacji HA z Exta Life poprzez subskrybcję tematu
homeassistant/# i monitorować co wysyła nam HA i czy HA reaguje na zmiany stanów poprzez wysyłanie wiadomości w tematach MQTT dla zmian stanów dla urządzeń.
Testy wykonujemy poprzez zmianę stanów naszego wirtualnego urządzenia MQTT w widoku deweloperskim w widoku encji (url: /dev-state) i patrzymy w naszym kliencie MQTT co nam nasz HA wysyła i czy w ogóle. Jeśli nic się nie dzieje przy załączaniu/wyłączaniu urządzenia - patrzymy do loga HA w poszukiwaniu błędów inicjalizacji MQTT.
Chodzi o to, aby sprawdzić czy komunikacja brokera MQTT z HA działa poprawnie. Jeśli wszystko działa prawidłowo - usuwamy nasze wirtualne urządzenie z pliku konfiguracyjnego HA (configuration.yaml) i restart HA.
3. Rozpakować pliki z załącznika do jednego folderu na hoście/systemie, gdzie zainstalowany jest Python 3.5. Upewnić się, że w tym folderze jest dostęp do komendy
python, która uruchamia interpreter Python - czyli, że zmienna środowiskowa path ma wpisany katalog z interpreterem Python 3.5 lub nowszym.
UWAGA: w plikach skryptów shell
start_ha2exta.sh oraz
start_exta2ha.sh użyta jest komenda
python3, gdyż taka funcjonuje w moim systemie Synology. Jeśli u Was ta komenda jest inna np. po prostu
python to trzeba wyedytować te pliki .sh i podmienić komendę.
Okazuje się, że na danym systemie linux może być zainstalowanych kilka wersji interpretera Python np 2.5, 2.7 itp. W Synology właśnie dlatego jest oddzielna komenda do wywołania Python 3.5
4. Wyedytować plik
config.py i wprowadzić tam adresy IP i porty dla kontrolera EFC-01, brokera MQTT, a także wprowadzić użytkownika i hasło dla dostępu do kontrolera. Użytkownikiem nie musi być root ani adminitrator, ale także zwykły użytkownik. Zasada jest taka, że do Home Assistant dodadzą się automatycznie tylko te urządzenia Exta Life, które przypisane ma do siebie dany użytkownik aplikacji Exta Life.
5. Nadać skryptom (pliki .sh) uprawnienia do bycia wykonywalnymi: chmod +x
6. Przeprowadzić wstępną konfigurację programów (wygenerowanie pliku konfiguracji
exta_ha_config.yaml) poprzez uruchomienie skryptu
start_exta2ha.sh z parametrem
--testrun. Czyli pełna komenda w shellu:
./start_exta2ha.sh --testrun
Ten parametr spowoduje wygenerowanie pliku konfiguracyjnego, ale konfiguracja nie zostanie zapisana w HA na stałe, więc po restarcie HA wszystkie encje powstałe z wygenerowania konfiguracji znikną i można je ładować ponownie.
Jeśli zawartość pliku odpowiada oczekiwaniom co do mapowna na komponent HA to dalej do kroku 7. W przeciwnym przypadku wyedytować plik i uruchomić MQTT discovery (przesyłanie konfiguracji) poprzez uruchomienie skryptu
./start_exta2ha.sh --filediscovery
Ta komenda spowoduje wysłanie konfiguracji załadowanej z pliku konfiguracyjnego zamiast wygenerowanej w locie z danych otrzymanych z EFC-01.
Koniecznie zrestartować HA, aby zmiany w konfiguracji MQTT zostały zastosowaneJest jeszcze jeden parametr dla tego skryptu, który warto wspomnieć. W przypadku gdyby zaszła potrzeba wygenerowania pliku konfiguracyjnego od nowa (np. po nieudanej edycji) należy uruchomić skrypt z parametrem
--initialize.
Pełna komenda:
./start_exta2ha.sh --initialize
Plik wygeneruje się także za pierwszym uruchomieniem skryptu bez parametrów, lub po skasowaniu pliku konfiguracyjnego.
7. W widoku deweloperskim w HA GUI (URL z końcówką: /dev-state) sprawdzić, czy urządzenia Exta Life są widoczne jako encje light, switch, cover, sensor. W przypadku gdy mapowanie nie spełnia oczekiwań - powrót do punktu 6 i edycja pliku
8.
Wprowadzić encje urządzeń Exta Life do konfiguracji Home Assistant (configuration.yaml lub groups.yaml), aby były widoczne w GUI na kartach.Od wersji Home Assistant 0.86 domyślnym interfejsem użytkownika jest Lovelace. Tam nie ma konieczności edycji plików konfoguracyjnych, aby uwidocznić encje w interfejsie. Można wszystko wyklikać na zakładkach GUI. Więcej
tutaj9. Dodać skrypty start_exta2ha.sh oraz start_ha2exta.sh do autostartu swojego linuxa. W związku z tym że w różnych dystrybucjach linuxa są na to różne rozwiązania - odsyłam po pomoc do Google. Ja w moim Synology dodałem je po prostu w Panelu Sterowania jako Zadania (Task scheduler) z automatycznym startem przy rozruchu DSM (triggered task, event: boot-up). Programy powinny być odporne na sytuację, gdy wystartowały wcześniej niż broker MQTT i Home Assistant oraz na niedostępność EFC-01, więc raz uruchomione powinny działać bez przerwy.
WAŻNE: testując te programy powalajcie im na nieprzerwaną pracę. Nie należy ich przerywać, ponieważ wtedy nic się nie będzie działo. MQTT nie będzie dostawać ani stanów urządzeń Exta Life, ani konfiguracji. Programy te pełnią w pewien sposób rolę usług systemowych (tzw. daemon'ów), choć nimi nie są. Minus jest taki, że blokują konsolę ssh i aby robić coś innego na linuxie to musicie odpalić osobną sesję. Niestety jest tak ze względu na to, że różne dystrybucje mają różne sposoby na tworzenie usług. Ja chciałem przygotować rozwiązanie uniwersalne, które ruszy na każdej maszynie. Stąd "czysty" program, który ma w sobie nieskończoną pętle, a nie prawdziwa usługa działająca w tle i nieblokująca konsoli.
Do testów zamiast autostartu możecie spróbować też użyć linuksowej komendu nohup (odsyłam do google), która pozwala uruchomić każdy program w tle i tym samym nie będzie on blokował konsoli i (chyba) nie zostanie zamknięty przez Linuxa gdy odłączycie się od sesji ssh.
Od tej pory Wasza instalacja Exta Life wchodzi na nowy poziom swojej egzystencji i pozwala być sterowaną z pięknego i minimalistycznego GUI wraz z całą masą innych smart-urządzeń w Waszym domu poprzez znacznie bardziej złożone scenariusze automatyki domowej.
Po spędzeniu godzinki czasu na konfiguracji komponentu HA o nazwie
'Google Assistant' będziecie też w stanie sterować swoją Extą z aplikacji Google Home oraz poprzez Asystenta Google (po angielsku już to działa, a po polsku zacznie od połowy stycznia).
Miłej zabawy!
EDIT 10.01.2019
Dodano poprawkę
main_ha2exta.py w wersji 1.0.1 w załączniku
EDIT 15.01.2019
Dodano poprawkę
main_ha2exta.py w wersji 1.0.2 w załączniku
EDIT 17.09.2019
Wersja 1.0.2 - dodano obsługę czujnika temperatury z RNK-22 oraz poprawiono crash, gdy wykryte są nieobslugiwane urządzenia