ESPHome

Ten samouczek przeprowadzi cię przez projektowanie interfejsu w Lopaka i eksportowanie go do konfiguracji ESPHome dla dowolnego mikrokontrolera obsługiwanego przez ESPHome.

Czym jest ESPHome?

ESPHome zamienia popularne mikrokontrolery ESP8266/ESP32 w urządzenia inteligentnego domu zarządzane za pomocą jednego pliku YAML. Jego komponent display: obsługuje szeroką gamę ekranów — OLED, TFT, e-paper i inne — używając lambdy C++ do poleceń rysowania.

Pierwsze kroki z ESPHome i Home Assistant: https://esphome.io/guides/getting_started_hassio/

Wymagania wstępne

• Urządzenie obsługiwane przez ESPHome.
• Podstawowa konfiguracja YAML ESPHome dla twojego urządzenia ze zdefiniowaną platformą display.

Krok 0: Utwórz nowy projekt

1. Przejdź do lopaka.app i utwórz nowy projekt.
2. Wybierz ESPHome z listy platform.
3. Ustaw Rozmiar ekranu tak, aby odpowiadał rozdzielczości twojego wyświetlacza.
4. Ustaw kolor tła (domyślnie czarny #000000).

Krok 1: Zaprojektuj i wyeksportuj z Lopaka

1. Narysuj swój interfejs za pomocą paska narzędzi. Nazwij każdą warstwę wyraźnie — nazwy warstw stają się komentarzami w kodzie i nazwami zmiennych w danych wyjściowych. Użyj ikony oka na liście warstw, aby ukryć warstwy, których nie chcesz eksportować.
2. W panelu Ustawienia kodu skonfiguruj opcje eksportu:
   • Dołącz czcionki — wymagane, jeśli używasz niestandardowego tekstu lub czcionek.
   • Deklaruj obrazy — włącz, jeśli twój projekt zawiera ikony lub namalowaną grafikę.
   • Deklaruj zmienne — włącz, jeśli twój interfejs opiera się na dynamicznych danych.
3. Odznacz Funkcja opakowująca, jeśli wklejasz bezpośrednio do istniejącego bloku lambda: ESPHome, aby Lopaka wypisywała tylko wywołania rysowania it.*.
4. Kliknij Kopiuj, aby zapisać wygenerowany kod do schowka.

Charakterystyka platformy

Zanim zaczniesz rysować, zwróć uwagę na ograniczenia, które dotyczą wszystkich projektów ESPHome w Lopaka:

• Model kolorów: pełny RGB. Kolory są kodowane jako Color(R, G, B) w wygenerowanej lambdzie; biały jest domyślną wartością ESPHome (COLOR_ON), więc Lopaka pomija argument koloru dla białych warstw.
• Obrazy: tylko XBMP (jednobitowa monochromia) — nie ma eksportu bitmap RGB dla ESPHome. Ikony i warstwy malowane są zawsze eksportowane jako bitmapy binarne.
• Brak zaokrąglonych prostokątów: API wyświetlacza ESPHome nie ma prymitywu zaokrąglonego prostokąta.

Dostępne narzędzia rysowania

Wszystkie standardowe narzędzia Lopaka są dostępne dla projektów ESPHome:

Narzędzie	Metoda ESPHome
Linia	it.line(x1, y1, x2, y2, color)
Prostokąt (kontur)	it.rectangle(x, y, w, h, color)
Prostokąt (wypełniony)	it.filled_rectangle(x, y, w, h, color)
Koło (kontur)	it.circle(x, y, r, color)
Koło (wypełnione)	it.filled_circle(x, y, r, color)
Trójkąt (kontur)	it.triangle(x1,y1, x2,y2, x3,y3, color)
Trójkąt (wypełniony)	it.filled_triangle(x1,y1, x2,y2, x3,y3, color)
Wielokąt	Seria wywołań it.line()
Tekst	it.print(x, y, id(font), color, "text")
Ikona / obraz	it.image(x, y, id(image), color)

Krok 2: Dodaj kod do ESPHome

1. Otwórz plik konfiguracji YAML ESPHome swojego urządzenia.
2. Znajdź komponent display i jego blok lambda lub użyj bloku z Lopaka, jeśli taki nie istnieje.
3. Wklej kod renderowania interfejsu wewnątrz sekcji lambda. Upewnij się, że wcięcie (tabulatory lub spacje) odpowiada ścisłym wymaganiom YAML ESPHome.

Gdy ustawienie Funkcja opakowująca jest włączone, pełne dane wyjściowe wyglądają tak:

font:
    - file: 'gfonts://Roboto'
      id: roboto_24
      size: 24

display:
    lambda: |-
        // title
        it.print(10, 10, id(roboto_24), "Hello ESPHome!");
        // border
        it.rectangle(0, 0, 128, 64);

Wklej to na poziomie głównym swojego pliku YAML. Jeśli masz już sekcję font: lub display:, połącz nowe wpisy zamiast duplikować klucz.

Krok 3: Napraw błędy czcionek i deklaracji

Częstym błędem podczas wklejania kodu z Lopaka bezpośrednio do ESPHome są brakujące lub nieprawidłowo umieszczone deklaracje czcionek.

Przenieś czcionki poza lambdę

Kod wyeksportowany z Lopaka zawiera sekcję font:. Musi ona zostać umieszczona na poziomie głównym twojego pliku YAML — nie wewnątrz lambdy display.

Uwaga

font: i image: to klucze YAML najwyższego poziomu. Umieszczenie ich wewnątrz ciągu lambda: spowoduje błąd kompilacji.

Usuń duplikaty

Jeśli twoja konfiguracja ESPHome ma już blok font:, nie dodawaj drugiego. Połącz wpisy czcionek z Lopaka z istniejącymi deklaracjami.

Typy czcionek

Google Fonts to najłatwiejsza opcja — pobierane automatycznie w czasie kompilacji przez gfonts://:

font:
    - file: 'gfonts://Roboto'
      id: roboto_24
      size: 24

Obrazy

Warstwy ikon i malowane są konwertowane do XBMP i eksportowane jako obrazy BINARY. Ustawienia kodu → Obrazy wyświetla każdy obraz jako <Name>.png, nazwany od jego warstwy; YAML odwołuje się do niego jako images/<Name>.png. Pobierz plik PNG i umieść go w podfolderze images/:

# You may need to download images and put them into esphome folder
image:
    - file: 'images/my_icon.png'
      id: img_my_icon
      resize: 32x32
      type: BINARY

Zmienne

Włącz Deklaruj zmienne, aby właściwości warstw były dynamiczne w czasie działania. Każda właściwość warstwy (pozycja, rozmiar, tekst, kolor) oznaczona jako zmienna jest wyodrębniana do deklaracji z typem na górze lambdy:

const char* my_label_text = "Hello";
int my_label_x = 10;

// my_label
it.print(my_label_x, 20, id(roboto_24), my_label_text);

Nazwy zmiennych pochodzą z tytułu warstwy — zmień nazwy warstw na liście warstw, aby uzyskać czyste nazwy w danych wyjściowych.

Odczytywanie wartości z ESPHome i Home Assistant

Wyłącz Deklaruj zmienne, aby rysować tekst pochodzący z komponentu ESPHome, takiego jak sensor lub text_sensor Home Assistant. Oznacz tekst warstwy tekstowej jako zmienną i nazwij warstwę od id komponentu:

• Zwykły tekst odczytuje wartość tekstową: it.print(30, 20, id(Montserrat_26), id(day_of_week).state.c_str());
• Tekst z formatem printf, takim jak %.1f °C, wypisuje wartość liczbową: it.printf(75, 298, id(Montserrat_30), "%.1f °C", id(temp_in).state);

Wartości czujników są liczbami zmiennoprzecinkowymi, więc używaj %.0f, %.1f itd. i pisz %% dla dosłownego znaku procentu. Obszar rysowania pokazuje tekst formatu tak, jak go wpisano. Zadeklaruj pasujący blok sensor: lub text_sensor: z tym samym id w swoim pliku YAML.

Krok 4: Zainstaluj i wgraj

Gdy czcionki zostaną prawidłowo oddzielone od lambdy i nie pozostaną żadne błędy walidacji:

1. Kliknij Install w panelu ESPHome.
2. Wybierz metodę instalacji — bezprzewodowo (OTA) lub przez USB.
3. Poczekaj, aż oprogramowanie układowe się skompiluje i wgraj. Po pomyślnym wgraniu twoje urządzenie uruchomi się ponownie i wyświetli interfejs, który utworzyłeś w Lopaka.

Odniesienie do ustawień kodu

Ustawienie	Domyślnie	Efekt
Funkcja opakowująca	Wł.	Opakowuje dane wyjściowe w blok display: lambda:
Komentarze	Wł.	Dodaje komentarz // nazwa warstwy przed każdym wywołaniem rysowania
Dołącz czcionki	Wł.	Wypisuje blok font: dla wszystkich używanych czcionek
Deklaruj obrazy	Wł.	Wypisuje blok image: dla wszystkich warstw bitmap
Deklaruj zmienne	Wł.	Wyodrębnia zmienne właściwości warstw do deklaracji z typem na górze lambdy

Rozwiązywanie problemów

Niezadeklarowana czcionka Brakuje bloku font: lub jest on umieszczony wewnątrz lambdy. Przenieś go na poziom główny swojego pliku YAML.

Zduplikowany klucz font Masz już blok font:. Połącz w nim wpisy czcionek z Lopaka zamiast dodawać drugi blok.

Nie znaleziono pliku obrazu Utwórz podfolder images/ obok swojego pliku YAML ESPHome i umieść tam pliki PNG.