homeassistant_espscreen/AGENTS.md

Werkinstructies voor LLM's en developers

Dit project bedient een ESP32-2432S028 met ILI9341 + XPT2046 (320×240, LVGL 90°). Lees README.md en docs/ voordat je installeert. De eigenaar kan fysiek tikken; een agent kan dat niet vervangen door softwarecoördinaten.

Een nieuw scherm installeren

1. Identificeer USB-poort en bordvariant. Gebruik ESPHome 2026.6.2 met Python 3.11–3.14. Controleer eerst of er lokale configuratie bestaat.
2. Maak in een verse kopie met tools/new_device.py een eigen device.yaml, calibration.yaml, secrets.yaml. Overschrijf nooit een werkend profiel. Laat de eigenaar wifi lokaal invullen. Toon geen sleutels in logs/chat.
3. Flash device.yaml met de CLI-substitutie CALIBRATION_ON_BOOT=true. Het geïsoleerde scherm heeft vijf kruisjes en werkt zonder HA.
4. Volg docs/CALIBREREN.md: geleide USB-capture, fit, flash, nieuwe capture, onafhankelijke verify. Vraag fysieke tikken per doel. Wacht op bevestiging dat het meetscherm werkelijk zichtbaar is; een geslaagde build is geen flash.
5. Flash zonder die override. Koppel de eigen HA via de ESPHome-integratie. Lees echte entity-ID's en ondersteunde attributen; verzin geen entiteiten.
6. Configureer alle gebruikte tegels volgens docs/TEGELS.md. De vacuumkaart zit op positie 6. Posities 8/10 hebben geen volledige slider/climatebinding. Test geen echte apparaat-acties zonder toestemming van de eigenaar.
7. Doorloop docs/ACCEPTATIE.md en rapporteer werkelijk uitgevoerde tests, beperkingen en de geobserveerde stabiliteitsduur.

Code en regressies

• Houd basishardware en UI in home-like-2432s028.yaml; eigen gegevens horen in de genegeerde lokale profielen. home-like.yaml is een ander oud profiel.
• Behoud vaste pagina's, verborgen navigatie bij maximaal zes tegels en minimaal 600 seconden standaard-standby. Geen vrij scrollen herintroduceren zonder touch-/navigatieregressies fysiek te testen.
• Behoud touchfilter en eventguard vóór acties; kalibratie verwerkt gefilterde fysieke ADC-waarden. Zet de affine correctie niet dubbel in driver en UI.
• Kalibratiewizard veronderstelt swap_xy=false, mirror_x=true, mirror_y=false en LVGL 90°. Een gewijzigde oriëntatie vereist ook nieuwe projectie/tests.
• Run Python-tests, beide C++-tests en ESPHome-validatie/build bij codewijzigingen. Firmwaretests en hardwareacceptatie zijn verschillende controles.
• diagnostics/run_ui_test.py rendert zonder HA-acties; raak tijdens die test het scherm niet aan. Gebruik --name voor de verwachte apparaatidentiteit.
• Deel via tools/export_bundle.py of Git. Stage geen secrets, metingen, binaries, logs, buildcache of lokale apparaatprofielen.
• Geen automatische firmware-upload naar een willekeurige aangesloten poort. Bij meerdere borden eerst de bedoelde poort vaststellen.

Historische diagnose is achtergrond, geen bewijs dat een nieuw paneel goed werkt. Maak tijdens onboarding geen claims over niet-uitgevoerde fysieke tests.