Jak tworzyć i testować szablony do Home Assistant? Jinja2, Developer Tools i Template

Interfejs graficzny Home Assistant opiera się o potężny język szablonów Jinja2. Jinja2 używany jest do przetwarzania danych z czujników, tworzenia warunków w automatyzacjach czy dynamicznego formatowania komunikatów. W celu ułatwienia pracy z Jinja2 Home Assistant oferuje wygodne narzędzie Template Editor w którym można żywo podglądać i testować działanie szablonów. Tutaj krótko przedstawię właśnie te narzędzie a potem pokażę kilkanaście przykładów na co pozwalają szablony.

Template Editor (edytor szablonów) jest dostępny w zakładce Developer Tools (Narzędzia deweloperskie) w menu Template (szablon):

Po jego otwarciu witają nas dwie kolumny - kod źródłowy szablonu oraz jego podgląd na żywo w HA:

Podgląd aktualizuje się sam - nie trzeba nic zapisywać, co wpiszemy po lewej, to otrzymamy po prawej.

1. Odczyt wartości encji
Zacznijmy od najprostszej rzeczy, czyli pobrania wartości jakiegoś sensora. Taki sensor oczywiście musi być już wcześniej sparowany z HA, np. poprzez Hass Discovery lub przez Zigbee.
Przykład:

Ten zapis zwróci aktualną wartość sensora sensor.temperature. Jeśli encja nie istnieje albo coś poszło nie tak, to nie pokaże błędu – tylko zwróci 'unknown'.

Tak można dobrać się do wielu wartości - przykładowo RSSI z OBK:


W wywołaniu states można określić też obecność jednostki oraz zaokrąglania:

To zwróci temperaturę z °C.
Poniższy kod z kolei ją zaokrągli:


2. Atrybuty encji
Czasem jednak sama wartość encji to za mało, np. w weather przyda się wilgotność czy stan zachmurzenia. To już nie states(), lecz state_attr():

Rezultat:

W celu debugowania można podejrzeć też cała encję dom:



3. Warunki i logika if
Tu zaczyna się zabawa. Jinja2 pozwala normalnie używać if, else, elif, jak w prostym skrypcie. Na próbę na razie wpisałem wartość na sztywno:

|float zamienia tekstową wartość encji na liczbę. W przeciwnym razie program będzie próbował porównywać napisy...

To samo, ale na przykładzie temperatury ze stanu urządzenia:

Taki szablon sam aktualizuje wyświetlany tekst, gdy coś się zmieni. Nie trzeba nic więcej dodawać.

4. Moment ostatniej zmiany encji
Czasami chcemy sprawdzić, kiedy dana encja ostatni raz zmieniła swój stan – np. kiedy zostały otwarte drzwi. Do tego służy właściwość last_changed.
Najprościej można wyciągnąć surowy timestamp:


Jeśli zamiast liczby w sekundach wolimy coś bardziej czytelnego – pełna data i czas:


Lub z własnym formatem:



5. Liczenie czasu
Analogicznie można policzyć ile czasu temu wydarzyło się dane zdarzenie - po prostu odejmujemy timestampy. Używany now() i as_timestamp():

To zwraca ile minut temu był ruch, zaokrąglone do jednego miejsca po przecinku.


6. Pętle – for i in
Jinja2 pozwala też przelecieć się po liście, np. po encjach danego typu. Taki szablon wypisuje wszystkie światła i ich stany:


Jeśli chcesz tylko te, które są włączone – da się dodać warunek w tej samej pętli:


To przydatne np. w powiadomieniach, automatyzacjach albo do debugowania stanu systemu bez przeklikiwania się przez interfejs.

7. Operacje matematyczne
W Jinja2 można wykonywać różne operacje matematyczne bezpośrednio w szablonach. Przykładowo, jeśli chcesz przeliczyć temperaturę z Celsjusza na Fahrenheita, wystarczy dodać prostą formułę:

Wynik zostanie zaokrąglony do jednego miejsca po przecinku dzięki filtrze round().


8. Operacje na tekście
Można też używać filtrów do manipulacji tekstem, np. zmiana wielkości liter:


To przydatne do standaryzacji tekstów w komunikatach lub wyświetlaniu ich w określonym formacie.
Często trzeba łączyć wartości z różnych encji lub dodać własne komunikaty. Jinja2 pozwala to zrobić poprzez operator ~:



9. Obsługa list i filtrowanie danych
Jinja2 umożliwia zaawansowaną pracę z listami. Przykładowo, jeśli chcesz zebrać nazwy wszystkich włączonych świateł w jednej linijce oddzielonej przecinkami, możesz użyć takiego szablonu:


To połączenie filtrów: selectattr wybiera elementy o podanym atrybucie, map pobiera wybrany atrybut (tu nazwę), a join scala listę w jeden tekst.

10. Sprawdzanie dostępności encji
Aby upewnić się, że encja istnieje przed jej użyciem:

Ten szablon sprawdza, czy encja sensor.temperature jest dostępna i nie zwraca wartości 'unknown'.



11. Wyświetlanie pełnej nazwy dnia tygodnia
Aby uzyskać pełną nazwę dnia tygodnia:


Funkcja strftime('%A') zwraca pełną nazwę dnia tygodnia, np. "niedziela".


12. Makra (do wielokrotnego użytku)
Można też zdefiniować makro którego potem będzie dało się używać wielokrotnie:

Rezultat:


13. Losowy wybór z listy
Wybierz losowo jedną wartość z listy:



14. Suma i średnia z listy
W Jinja też można utworzyć listę i ją zsumować:


Analogiczne - średnia:


To na razie tyle przykładów ode mnie. Po więcej informacji zapraszam do dokumentacji HA w języku angielskim: https://www.home-assistant.io/docs/configuration/templating/

Podsumowując, Jinja2 jest wszechstronnym i użytecznym językiem szablonów w HA. Jej składnia może na początku wydawać się niezbyt intuicyjna, ale mam nadzieję, że pokazane tu przykłady pomogą Wam z nią wystartować. Czy korzystacie z własnych szablonów Jinja2 w swoim HA, a jeśli tak to do czego?

W kolejnej części postaram się pokazać praktyczne przykłady szablonów Jinja2 w Home Assistant, razem z urządzeniami i z tym jak i gdzie ich użyłem.