Home Assistant ESP Screens

Nieuw scherm installeren? Begin met Easy Setup. Installeer ESP Screen Manager in Home Assistant, download de YAML voor CYD of Guition, flash eenmaal via USB op je Raspberry en kies je tegels in de beheerpagina. Zoeken op entiteit/apparaat/ruimte, slepen, opslaan — zonder opnieuw flashen.

Updates van de app behouden je indelingen. Nieuwe firmware installeer je via ESPHome OTA met behoud van je eigen naam, wifi en sleutels. Zie updates publiceren.

De handleiding hieronder blijft beschikbaar voor handmatige installatie via een computer. Voor de handmatige Guition-route: Guition.

CYD Home Assistant-bedieningsscherm

Van een nieuwe ESP32-2432S028 met ILI9341 + XPT2046 naar een gekalibreerd Home Assistant-scherm, via USB. Met lichtbediening, scènes/scripts, climate, vacuum, maximaal tien tegels en vaste pagina's. Bij maximaal zes tegels verdwijnt de paginering. Standby begint standaard na tien minuten.

Handmatige installatie via de computer: je hoeft geen Home Assistant-token te maken of een ESPHome-add-on te installeren om via de computer te flashen.

Met een LLM of developer werken

Geef de uitgepakte map en deze opdracht:

Lees eerst AGENTS.md en README.md. Begeleid mij bij een nieuwe installatie op een ESP32-2432S028 die via USB is aangesloten, met mijn eigen Home Assistant. Controleer het bord, de seriële poort en de Python-omgeving. Maak een lokaal device.yaml-profiel; gebruik geen bestaande persoonlijke entiteiten of paneelkalibratie. Doorloop USB-kalibratie, HA-koppeling, tegelconfiguratie en de acceptatietest. Vraag mij om fysieke tikken wanneer nodig. Houd sleutels en wachtwoorden in lokale bestanden en rapporteer welke controles echt zijn uitgevoerd.

De begeleider kan de code en logs lezen, maar kan het fysieke scherm niet vanzelf zien. Jij controleert het beeld en voert de gevraagde tikken uit.

1. Benodigdheden controleren

• Het bedoelde bord: ESP32-2432S028, 320×240, ILI9341-display en resistieve XPT2046-touch. Er bestaan borden met bijna dezelfde naam en een andere schermcontroller. Deze handleiding garandeert die varianten niet.
• Een USB-datakabel en een computer met macOS, Linux of Windows.
• Python 3.11–3.14, internet voor de eerste build en enkele GB vrije ruimte. De versiegrens komt uit het geteste ESPHome-pakket; gebruik geen Python 3.15.
• Een 2,4GHz-wifinetwerk; Home Assistant moet het bord via het netwerk kunnen bereiken. Houd het wifiwachtwoord lokaal beschikbaar.
• Toegang tot Home Assistant om entiteiten te kiezen en ESPHome toe te voegen.

Gebruik bij voorkeur één aangesloten ESP-bord tegelijk. Noteer de variant en het MAC-adres uit de boot-/uploadlogs. home-like.yaml en buttons.yaml uit het oorspronkelijke project zijn niet de startersconfiguratie voor dit bord.

2. De werkomgeving installeren

Kloon de repository of pak de starter-ZIP uit. Open een terminal in de codefolder. Alle opdrachten hieronder worden vanuit die folder uitgevoerd.

macOS/Linux:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Windows PowerShell:

py -3.13 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Als PowerShell activeren blokkeert, gebruik rechtstreeks .\.venv\Scripts\python.exe in plaats van python; een systeemwijziging is niet nodig. Controleer daarna:

python --version
python -m esphome version
python -m serial.tools.list_ports

Verwacht ESPHome 2026.6.2. Deze repo bevat een aangepaste touchdriver die met deze versie is getest. Upgrade niet stilzwijgend tijdens een installatie. Zie ook de officiële ESPHome-installatiehandleiding.

Noteer de poort: bijvoorbeeld /dev/cu.usbserial-130 op macOS, /dev/ttyUSB0 op Linux of COM3 op Windows. Verderop staat <USB_POORT>; vervang dat steeds door de werkelijke poort, zonder punthaken.

3. Een eigen apparaatprofiel maken

Kies een unieke naam, bijvoorbeeld display-keuken:

python tools/new_device.py --name display-keuken --friendly-name "Display keuken"

Dit maakt drie lokale bestanden en overschrijft niets:

Bestand	Wat je erin aanpast
device.yaml	Apparaatnaam, ruimte, tegels en gedrag
calibration.yaml	Kalibratie van dit ene fysieke paneel; de wizard schrijft dit
secrets.yaml	Wifi, API-encryptiesleutel, OTA- en fallbackwachtwoord

De sleutels worden uniek gegenereerd. Vul in secrets.yaml alleen jouw wifi_ssid en wifi_password in. Laat de gegenereerde sleutels staan en bewaar dit bestand bij je eigen configuratie. Deel het niet mee in de ZIP. De API-encryptiesleutel heb je later nodig bij de HA-koppeling; kopieer die lokaal uit het bestand, niet via een openbare chat.

Bestaan deze bestanden al? Werk in een nieuwe kopie van de map voor een nieuw scherm. Wis de sleutels/kalibratie van een werkend scherm niet.

device.yaml importeert de basis en jouw kalibratie. Het overschrijft ook alle verborgen tegelposities, zodat die geen entiteiten van iemand anders blijven volgen. Begin met de zes voorbeeldtegels. DIRECT_ACTIONS: "false" voorkomt directe HA-aansturing tijdens de eerste installatie. Maak in deze fase nog geen HA-automations die op de actie-sensor reageren.

4. Eerste USB-flash en kalibratie

Controleer eerst de configuratie (ESPHome schermt secrets standaard af):

python -m esphome config device.yaml

Flash de kalibratiemodus, die zonder HA-verbinding werkt:

python -m esphome -s CALIBRATION_ON_BOOT true run device.yaml --device <USB_POORT>

De eerste build kan meerdere minuten duren. Na upload verschijnen vijf kruisjes op een donker scherm. run blijft logs tonen: stop alleen de loglezer met Ctrl+C voordat je de kalibratiewizard start. Het bord blijft aan.

Volg nu docs/CALIBREREN.md: per doel worden drie tikken verzameld, de vier hoeken bepalen de correctie en het midden is een onafhankelijke controle. Daarna flash je de uitkomst en meet je opnieuw. Kopieer nooit de meetwaarden van een ander paneel.

5. Home Assistant koppelen

Na een geslaagde kalibratie flash je de normale modus:

python -m esphome run device.yaml --device <USB_POORT>

Controleer in de logs de wifi-IP, stabiele boot en apparaatnaam. Ctrl+C sluit de loglezer. Het scherm moet nu de normale tegelpagina tonen.

1. Open in HA Instellingen → Apparaten & diensten.
2. Kies het ontdekte ESPHome-apparaat, of Integratie toevoegen → ESPHome.
3. Gebruik display-keuken.local of het IP-adres uit de logs; API-poort 6053.
4. Vul de api_encryption_key uit je lokale secrets.yaml in als daarom wordt gevraagd.
5. Controleer of de apparaatnaam klopt en de status online wordt.
6. Open de opties/configuratie van deze ESPHome-integratie en schakel Allow the device to perform Home Assistant actions in.

De precieze vertaling/plaats van de optie verschilt per HA-versie. Zie de officiële integratiehandleiding. De HA-integratie verbindt met het bord; de ESPHome Device Builder/add-on is optioneel en is een andere functie.

6. Eigen tegels instellen

Volg docs/TEGELS.md. Verzamel de echte entity-ID's in HA, controleer ondersteunde attributen/acties en pas device.yaml aan. Gebruik korte titels. Als je alles hebt gecontroleerd:

substitutions:
  DIRECT_ACTIONS: "true"
  TILE_COUNT: "6"

Dit zijn wijzigingen in de bestaande substitutions-map, geen tweede map onderaan het bestand. Bouw en flash opnieuw met run device.yaml. De tegels volgen daarna de werkelijke HA-status. Een actieve API-verbinding alleen bewijst nog niet dat een actie door HA is toegestaan.

7. Opleveren en testen

Voer docs/ACCEPTATIE.md uit. Dat omvat een onafhankelijke touchmeting, beide pagina's indien aanwezig, lange druk, sliders, climate, vacuum, werkelijke HA-status en de juiste actie-effecten. De ingebouwde renderproef stuurt zelf geen HA-apparaten aan:

python diagnostics/run_ui_test.py --host display-keuken.local --name display-keuken

Bewaar bij deze persoon: device.yaml, calibration.yaml, secrets.yaml, de meetbestanden, de gebruikte ESPHome-versie en een kort opleverrapport. Voor later bijwerken kun je USB blijven gebruiken of OTA gebruiken:

python -m esphome run device.yaml --device display-keuken.local

Verander naam/API-sleutel niet zonder ook de HA-koppeling bij te werken. Bij storing: docs/PROBLEMEN.md.

Deze code aan de volgende persoon geven

Gebruik de exporteur in plaats van je hele werkmap te kopiëren:

python tools/export_bundle.py --output dist/cyd-starter.zip

De ZIP bevat de code, lokale fonts, licenties, handleidingen en neutrale voorbeelden. De basisdefaults worden voor de ontvanger geneutraliseerd. Geen secrets.yaml, eigen device.yaml, metingen, logs, .git, .esphome, Python-omgeving of firmwarebackups. De exporteur weigert een bestaande ZIP te overschrijven; kies bij een nieuwe versie een andere bestandsnaam.

De originele basis is van akuehlewind/ESPHome-touch-display-mount. Project-, ESPHome-driver- en fontlicenties staan respectievelijk in LICENSE, components/xpt2046/LICENSE en fonts/. Historische borddiagnose staat in CYD_STABILITY.md; volg voor een nieuwe installatie de handleidingen hierboven.