aztouch-esphome

ESPHome-Konfiguration für das AZTouch 2.8"-Shield (AZ-Delivery) auf ESP32 DevKit, aufgeteilt in wiederverwendbare Packages, die der ESPHome Device Builder direkt aus diesem Repo nachlädt.

Ersetzt die Arduino/TFT_eSPI-Variante aus ppfeiffer/aztouch-ha-modbus, die als Referenz für Pinbelegung und Modbus-Anbindung bestehen bleibt.

---

Hardware

Komponente	Modell
Microcontroller	ESP32 DevKit (AZ-Delivery)
Display-Shield	AZTouch 2.8" – ILI9341 320×240
Touch	XPT2046 (resistiv, gleicher SPI-Bus)
RS485 (optional)	Modbus-RTU-Modul TTL↔RS485 an UART2

Pinbelegung

Fest verdrahtet auf der AZ-Touch-MOD-Platine, Quelle: Schaltplan V01-03-01 (hwhardsoft.de). Nicht frei wählbar.

Signal	GPIO	Substitution
SPI SCK	18	spi_clk_pin
SPI MOSI	23	spi_mosi_pin
SPI MISO	19	spi_miso_pin
TFT CS	5	tft_cs_pin
TFT DC	4	tft_dc_pin
TFT RESET	22	tft_reset_pin
Touch CS	14	touch_cs_pin
Touch IRQ	27	touch_irq_pin
Backlight PWM (invertiert)	15	backlight_pin
Beeper	21	beeper_pin

GPIO21 ist der Beeper, im Schaltplan als BEEPER bezeichnet und fest über einen Transistor mit dem Piezo verbunden. Wird der Pin für etwas anderes verwendet — etwa als Chip-Select — knattert der Buzzer im Takt der Signalwechsel.

Freie Lötpads in der Proto-Fläche: GPIO32, GPIO25, GPIO26, GPIO33, GPIO34, GPIO35, GPIO39, A0. Modbus lässt sich dort auflegen.

---

Inbetriebnahme

Vor dem Vollausbau erst die Hardware prüfen. bringup-loader.yaml lädt nur hardware.yaml und display-bringup.yaml — kein LVGL, kein Home Assistant, keine Fonts. Erwartet werden drei senkrechte Farbbalken (rot/grün/blau), ein weißes Quadrat oben links als Orientierungsmarke und ein kurzer Ton beim Start.

Beobachtung	Bedeutung
Ton kommt, Display bleibt dunkel	Firmware läuft, Backlight nicht — backlight_inverted umstellen
Kein Ton	Firmware startet nicht durch, Log auf DEBUG prüfen
Balken erscheinen, Farben vertauscht	invert_colors umstellen
Bild steht quer oder gespiegelt	display_rotation anpassen
Touch-Zeilen fehlen im Log	Touchcontroller oder interrupt_pin prüfen
Touch reagiert seitenverkehrt	transform: mirror_x / mirror_y / swap_xy

Die Rohwerte aus den Touch-Logzeilen sind gleichzeitig die Grundlage für die calibration-Werte in hardware.yaml.

Läuft das, auf aztouch-loader.yaml wechseln.

Nutzung im ESPHome Device Builder

1. aztouch-loader.yaml aus diesem Repo nach /config/esphome/aztouch.yaml kopieren (Name frei wählbar).
2. In /config/esphome/secrets.yaml ergänzen: wifi_ssid, wifi_password, wifi_ap_password, api_encryption_key, ota_password.
3. Substitutions im Loader an die eigenen Entities anpassen.
4. Installieren – die Packages werden zur Compile-Zeit per git geholt.

Der Loader enthält bewusst nur Gerätename, Substitutions, WLAN, API und OTA. Alles andere kommt aus packages/.

Versionsbindung

packages:
  aztouch:
    url: https://git.pfeiffer-privat.de/ppfeiffer/aztouch-esphome
    ref: master        # oder ein Tag, z.B. v0.1.0
    refresh: 0s        # 0s = bei jedem Build fetchen, 1d = einmal täglich

ref: master heißt: jeder Push landet beim nächsten Build auf dem Gerät. Für stabile Panels besser einen Tag pinnen.

Privates Repo

Falls das Repo auf privat gestellt wird, im packages:-Block ergänzen:

    username: ppfeiffer
    password: !secret forgejo_token

---

Packages

Datei	Inhalt	Pflicht
packages/base.yaml	Logger, Zeit, Fonts, Diagnose-Entities	ja
packages/hardware.yaml	Board, SPI, Display, Touch, Backlight	ja
packages/display-lvgl.yaml	display + touchscreen für LVGL	ja*
packages/display-bringup.yaml	display + touchscreen mit Testbild	ja*
packages/ui.yaml	LVGL-Tileview mit 7 Kacheln	ja*
packages/ha_sources.yaml	HA-Entities → LVGL-Widgets	optional
packages/modbus.yaml	UART2 + Modbus RTU	optional

Kacheln

0 Übersicht | 1 Solar | 2 Garten | 3 Steuerung | 4 Heizung | 5 Energie | 6 Wetter

---

CI

Geprüft wird ausschließlich in der CI. Es gibt keine lokale Validierungsumgebung und keine eingecheckte venv — maßgeblich ist der Workflow-Lauf in Forgejo.

.forgejo/workflows/validate.yml führt bei jedem Push und bei PRs ein esphome config tests/ci-loader.yaml aus. Der CI-Loader bindet die Packages lokal ein, prüft also genau den gepushten Stand – nicht den zuletzt veröffentlichten.

Damit tauchen ESPHome-Breaking-Changes im Build-Log auf statt erst beim Flashen auf dem Panel.

Voraussetzung: die Actions-Variable CI_GIT_URL am Repo muss auf die instanzintern erreichbare Adresse der Forgejo-Instanz zeigen. Die öffentliche Domain funktioniert aus dem Runner-Container heraus nicht.

Der Workflow installiert jeweils das aktuelle ESPHome. Damit schlägt ein Release mit Breaking Changes beim nächsten Push auf — und nicht erst beim Flashen auf dem Panel.

Zuletzt grün gegen ESPHome 2026.7.2.

---

Offene Punkte

• Touch-Kalibrierung in hardware.yaml sind ungeprüfte Startwerte. Am realen Panel ermitteln: logger: level: DEBUG, Ecken antippen, Rohwerte übernehmen. Richtung nicht über vertauschte Grenzwerte korrigieren, sondern über transform: mirror_x / mirror_y / swap_xy — ESPHome lehnt x_min > x_max ab.
• RAM: Der DevKit hat kein PSRAM. Heap im Log beobachten; bei Problemen auf ESP32-WROVER wechseln (pinkompatibel) und psram: im Loader aktivieren.
• Diagramme: Das LVGL-Widget chart ist in ESPHome nicht implementiert. Verlaufsgrafiken bleiben deshalb in Home Assistant; auf dem Panel stehen nur Momentanwerte.
• invert_colors steht auf false. Bei invertierten Farben umstellen.
• Modbus-Pins: UART2 auf GPIO16/17 kollidiert nicht mit der Platine, ist aber ungeprüft. Die freien Pads der Proto-Fläche sind die sichere Wahl.
• Modbus DE/RE: Nur bei Modulen ohne Auto-Direction nötig, dann flow_control_pin in modbus.yaml einkommentieren.
• Strapping-Pins: ESPHome warnt zu GPIO15 und GPIO2. Auf dem AZTouch-Shield ist das die vorgegebene Beschaltung; falls der ESP32 gelegentlich nicht bootet, hier ansetzen.

---

Weiterarbeit

• CLAUDE.md – Kontext, Konventionen und Fallstricke für Claude Code
• docs/DECISIONS.md – warum das Projekt so aussieht, wie es aussieht
• CHANGELOG.md – Versionshistorie

Lizenz

MIT