ESPHome

Dieses Tutorial zeigt dir, wie du in Lopaka eine Oberfläche gestaltest und sie als ESPHome-Konfiguration für jeden von ESPHome unterstützten Mikrocontroller exportierst.

Was ist ESPHome?

ESPHome macht aus gängigen ESP8266/ESP32-Mikrocontrollern Smart-Home-Geräte, die über eine einzige YAML-Datei verwaltet werden. Seine Komponente display: steuert eine große Bandbreite an Displays – OLED, TFT, E-Paper und mehr – und nutzt dafür ein C++-Lambda mit den Zeichenbefehlen.

Erste Schritte mit ESPHome und Home Assistant: https://esphome.io/guides/getting_started_hassio/

Voraussetzungen

• Ein Gerät, das von ESPHome unterstützt wird.
• Eine einfache ESPHome-YAML-Konfiguration für dein Gerät mit einer definierten display-Plattform.

Schritt 0: Neues Projekt anlegen

1. Öffne lopaka.app und lege ein neues Projekt an.
2. Wähle ESPHome aus der Plattformliste.
3. Stelle die Screen-Größe passend zur Auflösung deines Displays ein.
4. Lege die Hintergrundfarbe fest (Standard ist Schwarz, #000000).

Schritt 1: In Lopaka gestalten und exportieren

1. Zeichne deine Oberfläche mit der Werkzeugleiste. Benenne jede Ebene eindeutig – Ebenennamen werden in der Ausgabe zu Code-Kommentaren und Variablennamen. Blende Ebenen, die nicht exportiert werden sollen, über das Augensymbol in der Ebenenliste aus.
2. Lege im Bereich Code-Einstellungen deine Exportoptionen fest:
   • Schriftarten einbinden – erforderlich, wenn du Text oder eigene Schriftarten verwendest.
   • Bilder deklarieren – aktivieren, wenn dein Design Icons oder gemalte Grafiken enthält.
   • Variablen deklarieren – aktivieren, wenn deine Oberfläche auf dynamischen Daten basiert.
3. Deaktiviere Wrapper-Funktion, wenn du den Code direkt in einen bestehenden ESPHome-Block lambda: einfügst – dann gibt Lopaka nur die Zeichenaufrufe it.* aus.
4. Klicke auf Kopieren, um den generierten Code in die Zwischenablage zu übernehmen.

Eigenschaften der Plattform

Beachte vor dem Zeichnen die Einschränkungen, die für alle ESPHome-Projekte in Lopaka gelten:

• Farbmodell: volles RGB. Farben werden im generierten Lambda als Color(R, G, B) kodiert; Weiß ist der ESPHome-Standard (COLOR_ON), daher lässt Lopaka das Farbargument bei weißen Ebenen weg.
• Bilder: nur XBMP (1-Bit-Monochrom) – für ESPHome gibt es keinen RGB-Bitmap-Export. Icons und gemalte Ebenen werden immer als binäre Bitmaps exportiert.
• Keine abgerundeten Rechtecke: Die Display-API von ESPHome hat keine Primitive für abgerundete Rechtecke.

Verfügbare Zeichenwerkzeuge

Alle Standardwerkzeuge von Lopaka stehen in ESPHome-Projekten zur Verfügung:

Werkzeug	ESPHome-Methode
Linie	it.line(x1, y1, x2, y2, color)
Rechteck (Umriss)	it.rectangle(x, y, w, h, color)
Rechteck (gefüllt)	it.filled_rectangle(x, y, w, h, color)
Kreis (Umriss)	it.circle(x, y, r, color)
Kreis (gefüllt)	it.filled_circle(x, y, r, color)
Dreieck (Umriss)	it.triangle(x1,y1, x2,y2, x3,y3, color)
Dreieck (gefüllt)	it.filled_triangle(x1,y1, x2,y2, x3,y3, color)
Polygon	Folge von it.line()-Aufrufen
Text	it.print(x, y, id(font), color, "text")
Icon / Bild	it.image(x, y, id(image), color)

Schritt 2: Code in ESPHome einfügen

1. Öffne die ESPHome-YAML-Konfigurationsdatei deines Geräts.
2. Suche die Komponente display und ihren lambda-Block – oder verwende den aus Lopaka, falls noch keiner existiert.
3. Füge den Code zum Zeichnen der Oberfläche in den Abschnitt lambda ein. Achte darauf, dass die Einrückung (Tabs oder Leerzeichen) den strengen YAML-Anforderungen von ESPHome entspricht.

Ist die Einstellung Wrapper-Funktion aktiv, sieht die vollständige Ausgabe so aus:

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);

Füge das auf der obersten Ebene deines YAML ein. Wenn du bereits einen Abschnitt font: oder display: hast, kombiniere die neuen Einträge, statt den Schlüssel doppelt anzulegen.

Schritt 3: Fehler bei Schriftarten und Deklarationen beheben

Ein häufiger Fehler beim direkten Einfügen von Lopaka-Code in ESPHome sind fehlende oder falsch platzierte Schriftart-Deklarationen.

Schriftarten aus dem Lambda herausnehmen

Der aus Lopaka exportierte Code enthält einen Abschnitt font:. Dieser gehört auf die oberste Ebene deines YAML – nicht in das display-Lambda.

Achtung

font: und image: sind YAML-Schlüssel der obersten Ebene. Stehen sie innerhalb des lambda:-Strings, führt das zu einem Kompilierfehler.

Duplikate entfernen

Wenn deine ESPHome-Konfiguration bereits einen font:-Block hat, füge keinen zweiten hinzu. Führe die Schriftart-Einträge aus Lopaka mit deinen bestehenden Deklarationen zusammen.

Schriftart-Typen

Google Fonts sind die einfachste Option – sie werden beim Kompilieren automatisch über gfonts:// geladen:

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

Bilder

Icons und gemalte Ebenen werden in XBMP umgewandelt und als BINARY-Bilder exportiert. Code-Einstellungen → Bilder listet jedes Bild als <Name>.png, benannt nach seiner Ebene; das YAML verweist darauf als images/<Name>.png. Lade das PNG herunter und lege es in einen Unterordner 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

Variablen

Aktiviere Variablen deklarieren, um Ebeneneigenschaften zur Laufzeit dynamisch zu machen. Jede als Variable markierte Ebeneneigenschaft (Position, Größe, Text, Farbe) wird als typisierte Deklaration an den Anfang des Lambdas gezogen:

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);

Variablennamen stammen aus dem Ebenentitel – benenne Ebenen in der Ebenenliste um, um saubere Namen in der Ausgabe zu erhalten.

Werte aus ESPHome und Home Assistant lesen

Deaktiviere Variablen deklarieren, um Text zu zeichnen, der aus einer ESPHome-Komponente stammt, etwa aus einem sensor oder text_sensor von Home Assistant. Markiere den Text der Textebene als Variable und benenne die Ebene nach der id der Komponente:

• Einfacher Text liest einen Textwert: it.print(30, 20, id(Montserrat_26), id(day_of_week).state.c_str());
• Text mit einem printf-Format wie %.1f °C gibt einen Zahlenwert aus: it.printf(75, 298, id(Montserrat_30), "%.1f °C", id(temp_in).state);

Sensorwerte sind Gleitkommazahlen, verwende also %.0f, %.1f usw. und schreibe %% für ein wörtliches Prozentzeichen. Die Zeichenfläche zeigt den Formattext so, wie du ihn eingegeben hast. Deklariere in deinem YAML den passenden Block sensor: oder text_sensor: mit derselben id.

Schritt 4: Installieren und flashen

Sobald die Schriftarten sauber vom Lambda getrennt sind und keine Validierungsfehler mehr bestehen:

1. Klicke im ESPHome-Dashboard auf Install.
2. Wähle die Installationsmethode – Wirelessly (OTA) oder Via USB.
3. Warte, bis die Firmware kompiliert und hochgeladen ist. Nach erfolgreichem Upload startet dein Gerät neu und zeigt die Oberfläche an, die du in Lopaka erstellt hast.

Referenz der Code-Einstellungen

Einstellung	Standard	Wirkung
Wrapper-Funktion	An	Umschließt die Ausgabe mit einem display: lambda:-Block
Kommentare, Ebenentitel	An	Fügt vor jedem Zeichenaufruf einen Kommentar // layer name ein
Schriftarten einbinden	An	Gibt den font:-Block für alle verwendeten Schriftarten aus
Bilder deklarieren	An	Gibt den image:-Block für alle Bitmap-Ebenen aus
Variablen deklarieren	An	Zieht variable Ebeneneigenschaften als typisierte Deklarationen an den Anfang des Lambdas

Fehlerbehebung

Font not declared Der font:-Block fehlt oder steht innerhalb des Lambdas. Verschiebe ihn auf die oberste Ebene deines YAML.

Duplicate key font Du hast bereits einen font:-Block. Führe die Schriftart-Einträge aus Lopaka darin zusammen, statt einen zweiten Block hinzuzufügen.

Image file not found Lege neben deinem ESPHome-YAML einen Unterordner images/ an und speichere die PNG-Dateien dort.