ESPHome Home Assistant + ESPHome - własne zabawki czyli custom components

[Gieneq]

Przeglądając listę możliwych integracji Home Assistant w większości jest tam to czego potrzebujemy. Sam byłem w szoku, gdy aplikacja podpowiedziała mi integrację z tunerem audio, o którym bym nawet nie pomyślał że się do tego nadaje. Problem pojawia się, gdy wymyślimy sobie własne DIY, które robi coś unikatowego i chcemy to podłączyć pod automatykę domowa.

Jedną z metod jest użycie Template Switch (czyli takiego wirtualnego przełącznika) i powiązanie go funkcją lambda z np. komponentem magistrali UART i komunikowanie się z naszym DIY. Problem w tym, że będziemy musieli poświęcić cały układ WiFi na pomost pomiędzy DIY, a centralką HA.

W tym artykule postaram się nakreślić, jak zacząć pisać własne komponenty do ESPHome.

Przygotowanie

Niby jest do tego instrukcja (custom sensor i custom generic component), ale mimo wszystko po przeczytaniu tego co tam zamieszczono, przejrzeniu przykładów, zapytaniu na oficjalnym kanale na Discordzie, odpowiedź znalazłem dopiero na szarym końcu internetu.

Wyjdźmy od tego jak tworzymy aplikacje (wsad np. do ESP8266 tu ESP-01S). Mając postawiony HA i zainstalowany dodatek ESPHome, dodajemy nowy sprzęt:

Wybieramy nazwę:

Rodzaj płytki:

Pomijamy wgrywanie, bo trzeba zmienić coś w konfiguracji. Wybieramy więc edit:

Mamy tu kilka domyślnych ustawień:

esphome:
  name: spectrum-display

esp8266:
  board: esp01_1m

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  password: "xxx"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "xxx"
    password: "xxx"

captive_portal:

Nazwa - potrzebna do mDNS jako hostname. Niestety po aktualizacji coś słabo działa. Na stronie ESPHome sugeruje się używanie statycznego IP, które ma też przyspieszać łączenie:

Cytat

It’s recommended to provide a static IP for your node, as it can dramatically improve connection times.

Dlatego dodajemy fragment dotyczący stałego IP:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  
  manual_ip:
    static_ip: 192.168.0.102
    gateway: 192.168.0.1
    subnet: 255.255.255.0
    
  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "xxx"
    password: "xxx"

Co w efekcie zobaczymy w logu:

Hasło do WiFi mamy ustawione w ESPHome (secrets). Zapisujemy, wgrywamy podłączając urządzenie przez USB lub wgrywając używając OTA, oczywiście jeżeli znamy hasło i adres urządzenia.

W moim przypadku jest ta druga opcja:

Gotowe komponenty

Komponent to pewna funkcjonalność (nawet bardzo rozbudowana). Np. może to być przełącznik światła dołączonego do konkretnego wyprowadzenia (patrz przykład). W przypadku bardziej rozbudowanych komponentów, np. obsłudze protokołu komunikacji, obsługa zawęża się do wskazania urządzenia (np. DS18B20 1-wire) i podania wyprowadzenia.

Takich komponentów możemy dodawać wiele i będą działać niezależnie od siebie. To tak jakbyśmy uruchomili wiele współbieżnych procesów. W praktyce wygląda to bardziej jak kod Arduino, w którym przy pomocy funkcji millis() wykonujemy "współbieżnie" wiele funkcji.

Podstawy za nami. Teraz konfigurację można wzbogacić o jakieś podstawowe komponenty. Przykładowo kod do sterowania diodą na płytce pod pinem 2:

# Enable Home Assistant API
api:

light:
  - platform: binary
    name: "Onboard LED"
    output: onboard_led_out

output:
  - id: onboard_led_out
    platform: gpio
    pin: GPIO2

Id posłuży nam do dodania tzw. encji czyli kontrolki na panelu widocznym w Home Assistant. Wgrywamy i przechodzimy do głównej strony i edytujemy widok panelu:

Od razu widzimy encję:

Modyfikujemy wedle uznania:

i gotowe! Możemy poklikać w nowo dodany przycisk. Najpewniej logika przycisku będzie odwrócona ze względu na sposób podłączenia LED na płytce ESP-01S. Możemy zmienić to w konfiguracji:

output:
  - id: onboard_led_out
    platform: gpio
    pin: GPIO2
    inverted: true

I działa  

Własny komponent

Napisanie własnego komponentu nie jest aż tak trudne. Autorzy uznali, że będą wzorować się na  koncepcji kodu Arduino , w którym można wyróżnić bloki setup() i loop(). Problem w tym, że nie wiadomo gdzie zapisać te pliki.

Na stronie z poradnikiem tworzenia własnych komponentów jest co prawda informacja:

Cytat

Store this file in your configuration directory, for example my_custom_component.h

Ale niewiele to wnosi, bo nigdzie nie jest napisane gdzie jest ten katalog... Z pomocą przychodzi test przykładowej konfiguracji, w której chcę dodać jakiś plik:

Czyli jest to ścieżka:

/config/esphome/

Sprawdźmy jak wygląda zawartość tego katalogu, tylko zanim do teog przejdziemy, potrzeba nam SSH - bo w systemie HA nie ma domyślnie takich udogodnień. W repozytorium znajdujemy SSH, ustawiamy hasło i możemy się zalogować. Użytkownik root, hasło własne, port 22. Używam polecenie ls z dopiskiem -a, aby wyświetlić ukryte pliki i katalogi:

la -a /config/esphome/

W tym miejscu można umieścić własne pliki bibliotek - tuż obok widzimy plik yaml konfiguracji. Ja swoje pliki umieszczam w katalogu custom_components tak by nie tworzyć bałaganu:

Wewnątrz katalogu tworzę plik fps_meter.h:

touch fps_meter.h

Do pracy korzystam z WinSCP i VSC - zapis pliku w VSC od razu zdalnie go aktualizuje:

Dla testu wpisuję kod służący do wyznaczania częstotliwości odświeżeni:

#include "esphome.h"

class FPSCounter : public Component, public Sensor {

  private:
    const unsigned long INTERVAL = 5000;
    unsigned long counter;
    unsigned long last_millis;
    float fps;

 public:
  float get_setup_priority() const override { return esphome::setup_priority::LATE; }

  void setup() override {
    last_millis = millis();
    int last_button_state = HIGH;
  }
  void loop() override {
    if(millis() - last_millis > INTERVAL) {
      fps = (1000.0 * counter) / (millis() - last_millis);
      ESP_LOGD("FPS_COUNTER", "%lu sec passed, FPS: %f", INTERVAL, fps);
      publish_state(fps);
      counter = 0;
      last_millis = millis();
    }
    ++counter;
  }
};

I zapisuję. Do tego jak działa ten kod jeszcze wrócimy, ale na razie istotne jest, że w pętli wykonywane jest sprawdzenie częstości odświeżania i okresowo informacja wysyła jest do HA. Komponent jest czujnikiem (dziedziczy po klasie Sensor) ponieważ zwraca pewne informacje do centralki.

Teraz trzeba użyć naszą klasę. Przechodzimy do konfiguracji i najpierw dodajemy plik biblioteki:

esphome:
  name: spectrum-display
  includes: 
    - custom_components/fps_meter.h

oraz tworzymy komponent:

api:

sensor:
- platform: custom
  lambda: |-
    auto fps_meter = new FPSCounter();
    App.register_component(fps_meter);
    return {fps_meter};

  sensors:
    name: "FPS counter"

light:
  - platform: binary
    name: "Onboard LED"
    output: onboard_led_out

output:
  - id: onboard_led_out
    platform: gpio
    pin: GPIO2
    inverted: true

Dodajemy typ sensor (to po czym dziedziczy nasz komponent), a w funkcji lambda korzystamy ze zdefiniowanej klasy FPSCounter. Dodajemy też nazwę, która może nam się przydać. Wgrywamy nowy kod i w logu zobaczymy, że coś zostało wyznaczone - mamy częstotliwość odświeżania około 60Hz:

Możemy też znaleźć nasz "czujnik" wśród encji:

i nasze obie kontrolki działają, powiedzmy "równolegle"  

Kod programu

Wracając na chwilę do kodu programu:

#include "esphome.h"

class FPSCounter : public Component, public Sensor {

 public:
  float get_setup_priority() const override { return esphome::setup_priority::LATE; }

  void setup() override {
  }
  void loop() override {
};

widzimy, że szablon jest dość prosty. Tworzymy klasę, która dziedziczy po komponencie i sensorze, aby móc wysyłać informacje (dostępna staje się wtedy metoda publish_state(). Jak wspomniałem setup i loop to metody, które możemy uzupełnić kodem wykonywanym odpowiednio przy starcie i cyklicznie. get_setup_priority() służy ustaleniu jaki priorytet ma nasza klasa. Możliwych narzędzi jest naprawdę wiele, zainteresowanych odsyłam do lektury dokumentacji i analizy przykładów.

Kod klasy możemy rozbić na osobne pliki .cpp i .h.

Warto jeszcze wspomnieć o czymś, co mnie bardzo mocno zmyliło - o bibliotekach/narzędziach deweloperskich ESPHome. W kodzie widzimy, że dodajemy plik esphome.h, ale nie jest to biblioteka:

W pliku tym mamy podlinkowane biblioteki, które będziemy używać, a sam plik wygenerowany zostanie automatycznie... zostanie, ponieważ nasza biblioteka jest w katalogu /config/esphome, ale przed kompilacją jest kopiowana do katalogu projektu:

Czyli dla powtórzenia:

• nasze pliki bibliotek trzymamy w głównym katalogu np. /config/esphome/custom_components/
• w pliku .yaml dodajemy ścieżkę: custom_components/plik_biblioteki.h
• w kodzie pliku plik_biblioteki.h dodajemy esphome.h jakby był tuż obok, bo przed kompilacją zostanie tam przekopiowany
• tworząc kod pamietamy żeby podlinkować zawartość katalogu src

Kuszące może być edytowanie zawartości katalogu src jednak tu uwaga w pliku README.txt:

THIS DIRECTORY IS AUTO-GENERATED, DO NOT MODIFY

ESPHome automatically populates the build directory, and any
changes to this directory will be removed the next time esphome is
run.

For modifying esphome's core files, please use a development esphome install,
the custom_components folder or the external_components feature.

Oznacza to, że ten katalog jest wygenerowany automatycznie na bazie pliku .yaml i nie powinniśmy w nim nic mieszać.

Edytowano Luty 2, 2022 przez Gieneq

[Woszu]

Witaj,

Fajny tekst, wszystko działa jak trzeba. Pytanie jak by to było w przypadku 2 custom sensors?

[Gieneq]

@Woszu w sumie ten temat gdzieś u mnie przepadł - miałem plan dodać to jako sterownik do wyświetlacza spektrum ale nie skończyłem wyświetlacza więc nie było okazji do kontynuacji.

Dodanie większej liczby własnych komponentów jest w tym miejscu:

sensor:
- platform: custom
  lambda: |-
    auto fps_meter = new FPSCounter();
    App.register_component(fps_meter);
    return {fps_meter};

jest to podobne do klas z C++, a przez dziedziczenie po Component i Sensor masz wystawione metody do łączenia z resztą.

[Woszu]

Zrobiłem tak:

	sensor:
	- platform: custom
	  lambda: |-
	    auto my_sensor = new MyCustomSensor();
	    App.register_component(my_sensor);
	    return {my_sensor->water_sensor, my_sensor->id_sensor};
	 
	  sensors:
	  - name: "Stan licznika wody"
	    unit_of_measurement: l
	    accuracy_decimals: 0
	  - name: "Id licznika wody"
	    accuracy_decimals: 0
	

 

a w pliku .h:

	class MyCustomSensor : public Component {
 public:
  Sensor *water_sensor = new Sensor();                            
  Sensor *id_sensor = new Sensor();
	//............
	{
	

 

Kompilacja przeszła, później zobaczę czy działa

[Woszu]

Działa bez problemu

[Woszu]

Cześć.

Walczę jeszcze z tym custom sensor component. W sumie z sukcesami, ale....

Prosty przykład przepisania wartości MeterID i jej opublikowanie w pliku h:

uint32_t MeterID = 1095753644;

class MyCustomSensor : public Component {
 public:                          
  Sensor *id_sensor = new Sensor();                              
  
void loop() { 
        id_sensor->publish_state(MeterID);
    }

 

natomiast w pliku yaml standardowo:

- platform: custom
  lambda: |-
    auto my_sensor = new MyCustomSensor();
    App.register_component(my_sensor);
    return {my_sensor->id_sensor}; 
  sensors:
  - name: "Meter Id"
    accuracy_decimals: 0

 

I coś dziwnego się dzieje, bo nie przechodzi ta wartość 1095753644 poprawnie. W esphome dostaję 1095753600.

Jakieś ograniczenia są w tym publish_state(), że mi obcina wartość?

Jak przesyłam mniejsze wartości (np. 10957536), to wtedy przechodzi ok....

Edytowano Grudzień 12, 2022 przez Woszu

[parasite]

Trafiłem na ten stary wątek więc go rozwiążę żeby na później już było

 

publish_state() w ESPHome nie przyjmuje uint32_t, tylko float (dokładnie: void publish_state(float state) - bo cała klasa Sensor w ESPHome jest float-based).

Co to oznacza?

• float w ESP32/Arduino ma 32 bity i tylko ok. 7 cyfr znaczących.

• Twoje 1095753644 mieści się w uint32_t, ale jako float nie da się go zapisać dokładnie.

• Stąd „obcina” i dostajesz najbliższą możliwą wartość, czyli 1095753600.

Dlatego mniejsze liczby (np. 10957536) wyglądają poprawnie, bo nadal mieszczą się w dokładności float.

 

Co możesz zrobić:

Traktować ID jako string (bo to nie jest liczba do obliczeń, tylko identyfikator).

cpp

TextSensor *id_sensor = new TextSensor();

void loop() override {
    id_sensor->publish_state(String(MeterID).c_str());
}

w YAML wtedy

- platform: custom
  lambda: |-
    auto my_sensor = new MyCustomSensor();
    App.register_component(my_sensor);
    return {my_sensor->id_sensor};
  text_sensors:
    - name: "Meter Id"

• Jeśli musi być liczba, to możesz przechowywać w dwóch polach (np. dzieląc na starsze i młodsze 16 bitów), albo jako uint32_t w global i tylko raportować jako string do HA.

• Ewentualnie użyj number lub template w HA i wysyłaj przez ESPHome API jako tekst, a potem konwertuj tam gdzie trzeba.