homeassistant_espscreen/AGENTS.md

Easy Setup en releases

De voorkeursroute voor nieuwe gebruikers is docs/EASY_SETUP.md: ESP Screen Manager plus remote ESPHome-pakketten. Geen token of blueprint nodig. Tegels staan in de permanente add-ondata; wifi/API/OTA blijven in de eigen ESPHome-YAML. Lees docs/RELEASING.md voordat je updates publiceert. Main distribueert beide borden. Genereer packages met tools/generate_packages.py; bewerk ze niet handmatig. Runtime-modus ondersteunt alle kaarten op alle tien posities. De positiebeperkingen hieronder gelden uitsluitend voor de oude handmatige profielen. Behoud gegevensschema, protocolcompatibiliteit, unieke sleutels en CYD-preferences. Test updates met bestaande gegevens. Publiceer geen onbekende opslagversie zonder migratie. Productie-Ingress heeft geen long-lived token of publieke poort nodig.

Guition-branch

De Guition 4848S040 heeft een apart profiel guition-4848s040.yaml met 480×480, ST7701S RGB en GT911. Lees docs/GUITION.md. Gebruik de eigen lokale guition-device.yaml; neem geen CYD-layout of XPT2046-kalibratie over. Controleer touch met tools/verify_gt911.py en houd de CYD-regressies groen. Configureer geen wallbox-relais als onderdeel van displayondersteuning.

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.