homeassistant_espscreen/docs/TEGELS.md

Tegels instellen voor jouw Home Assistant

Bewerk device.yaml, binnen de bestaande substitutions:. De basiscode hoef je voor de onderstaande voorbeelden niet aan te passen. Elke wijziging vraagt opnieuw bouwen en flashen. Doorloop eerst de installatie.

Entity-ID's verzamelen

Open in HA Ontwikkelaarstools → Statussen. Zoek de gewenste entiteit en kopieer de volledige ID, bijvoorbeeld light.keuken. Controleer status en attributen. De schermtitel is vrij te kiezen; de entity-ID moet exact kloppen. Test onder Ontwikkelaarstools → Acties de gewenste actie met die entiteit. Een actie kan het echte apparaat bedienen: kies een geschikte test. Zie HA-acties.

Maak eerst een lijst met positie, titel, entity-ID, tikactie en lange-drukactie. Gebruik bestaande HA-scripts/scènes voor meerdere apparaten of complexe logica.

Posities en grenzen

Posities	Bedoeld gebruik in deze firmware
1–6	Hoofdtegels; light, switch, scene, script, fan, cover en climate
6	Ook de vacuumkaart; de kaart is specifiek met tegel 6 verbonden
7 en 9	Extra lichttegels met helderheid/kleurbediening
8 en 10	Extra status-/actietegels; geen volledige numerieke/climatekaart

TILE_COUNT: "1" tot "10" bepaalt hoeveel opeenvolgende posities zichtbaar zijn. Tot en met zes zijn Vorige/Volgende verborgen; vanaf zeven staat 1–6 op pagina één en de rest op pagina twee. Vrij scrollen is vervangen door vaste pagina's. Laat ongebruikte posities op de neutrale voorbeeldentiteiten staan. Verander geen rastermaten om tegels toe te voegen.

Belangrijkste instellingen

Instelling (N = tegelnummer)	Betekenis
TILEN_ENTITY	Entiteit waarop de actie wordt uitgevoerd
TILEN_STATE_ENTITY	Entiteit voor status/attributen; meestal dezelfde
TILEN_TITLE	Korte titel, liefst maximaal circa 12 tekens
TILEN_TYPE	Domein, bijvoorbeeld light, scene, climate
TILEN_TAP_ACTION	auto, toggle of custom voor onderstaande voorbeelden
TILEN_TAP_SERVICE	Expliciete HA-actie bij custom, bijvoorbeeld script.turn_on
TILEN_LONGPRESS	none, slider of (alleen tegel 6) vacuum
TILEN_LONGPRESS_SLIDER	auto; kiest passende regeling op basis van type
TILEN_LABEL_ON/OFF	Tekst voor eenvoudige aan/uitstatus

De voorbeeldconfig vult ook de overige velden in. Laat die staan tenzij je ze bewust gebruikt. STATE_ENTITY kan bij een scène/script een echte lamp of schakelaar volgen; een scène heeft zelf geen betrouwbare aan/uitstatus.

Kleur, wittemperatuur en helderheid

Een RGB-/kleurenlamp met LONGPRESS: "slider" opent direct de lampkaart. Deze bevat maximaal drie horizontale schuiven:

• Kleur: een doorlopende regenboog (0–360° hue, 100% verzadiging).
• Wittemperatuur: warm naar koel, binnen de minimum-/maximum-Kelvinwaarden die de lamp in Home Assistant meldt.
• Helderheid: 1–100%; aan/uit blijft via de tegel beschikbaar.

De kleur- en witschuif verschijnen alleen als supported_color_modes deze ondersteunt. Een uitsluitend dimbare lamp houdt de gewone helderheidskaart. Er zijn geen extra tegelinstellingen nodig. Gebruik voor een lamp dezelfde ENTITY en STATE_ENTITY. De kleurkaart volgt hs_color, color_temp_kelvin, min_color_temp_kelvin en max_color_temp_kelvin van de bediende entiteit. Ontbreekt het temperatuurbereik, dan wacht de witschuif op HA-gegevens.

De kaart neemt bij openen de laatst ontvangen lampwaarden over. Slepen toont lokaal de gekozen waarde; pas loslaten verstuurt één opdracht. Kleur kiest de kleurmodus, wittemperatuur kiest de witmodus. Helderheid verandert de kleurmodus niet. De regenboog regelt hue; pastel/verzadiging is geen aparte regelaar. De hue-lijst wordt via ESPHome data_template naar HA gestuurd; zie de officiële API-documentatie.

De gedeelde implementatie staat in light_controls.h. Beide schermprofielen gebruiken deze; de Guition heeft grotere regelaars, de CYD een compacte kaart. diagnostics/run_ui_test.py controleert ook de schuifevents met vervangen callbacks: geen echte HA-acties. Voor een veilige 40-secondenvoorbeeldkaart:

python diagnostics/control_ui.py light_controls_preview --host guition-wallbox.local --name guition-wallbox

Gebruik voor CYD de eigen host en naam. Tijdens deze voorbeeldkaart worden lichtopdrachten onderdrukt en verdwijnt de kaart vanzelf. Test vervolgens de werkelijke lamp: lang indrukken, kleur kiezen, wit kiezen, helderheid aanpassen, sluiten en heropenen. Controleer de fysieke lamp en de waarden in HA.

Voorbeelden

Wijzig deze sleutels in de bestaande map; plak niet nogmaals substitutions:.

Dimbare lamp op positie 1 (tik schakelt, lang indrukken opent de regeling):

  TILE1_ENTITY: "light.keuken"
  TILE1_STATE_ENTITY: "light.keuken"
  TILE1_TITLE: "Keuken"
  TILE1_TYPE: "light"
  TILE1_TAP_ACTION: "auto"
  TILE1_LONGPRESS: "slider"

Een niet-dimbare lamp/schakelaar krijgt LONGPRESS: "none". Kleurbediening vereist dat de lamp de betreffende kleurmodus ondersteunt.

Scène op positie 3:

  TILE3_ENTITY: "scene.avond"
  TILE3_STATE_ENTITY: "light.keuken"
  TILE3_TITLE: "Avond"
  TILE3_TYPE: "scene"
  TILE3_TAP_ACTION: "auto"
  TILE3_LONGPRESS: "none"

Script op positie 4:

  TILE4_ENTITY: "script.alles_uit"
  TILE4_STATE_ENTITY: "script.alles_uit"
  TILE4_TITLE: "Alles uit"
  TILE4_TYPE: "script"
  TILE4_TAP_ACTION: "auto"
  TILE4_LONGPRESS: "none"

Airco op positie 5 (lang indrukken opent climate):

  TILE5_ENTITY: "climate.woonkamer"
  TILE5_STATE_ENTITY: "climate.woonkamer"
  TILE5_TITLE: "Airco"
  TILE5_TYPE: "climate"
  TILE5_TAP_ACTION: "toggle"
  TILE5_TAP_SERVICE: "climate.toggle"
  TILE5_LONGPRESS: "slider"

Controleer min_temp, max_temp, target_temp_step, hvac_modes en de ondersteunde fan-/swingmodes in HA. Deze kaart is primair voor een enkel setpoint, niet een thermostaat die uitsluitend een temperatuurinterval gebruikt. Test de modi van jouw integratie afzonderlijk; een andere airco kan andere mogelijkheden hebben.

Robotstofzuiger op positie 6 (tik start; lang indrukken opent de kaart):

  TILE6_ENTITY: "vacuum.robot"
  TILE6_STATE_ENTITY: "vacuum.robot"
  TILE6_TITLE: "Stofzuiger"
  TILE6_TYPE: "vacuum"
  TILE6_TAP_ACTION: "custom"
  TILE6_TAP_SERVICE: "vacuum.start"
  TILE6_LONGPRESS: "vacuum"

De vacuumkaart gebruikt start/pauze/stop/terugkeren/lokaliseren en de snelheidsnamen quiet, balanced, turbo, max. Vergelijk deze met de ondersteunde acties en fan_speed_list in HA. De snelheidsknoppen moeten in de basiscode aangepast worden als jouw integratie andere namen verwacht. Dit is geen universele kaart voor ieder robotmodel.

Acties inschakelen en controleren

Zet na kalibratie en HA-koppeling DIRECT_ACTIONS: "true". Geef in de ESPHome-integratie toestemming voor Home Assistant-acties. Gebruik geen HA-automation die dezelfde schermactie daarnaast nogmaals uitvoert; dat kan een dubbele toggle veroorzaken. Bij DIRECT_ACTIONS: "false" kan de actie-sensor nog gebeurtenissen publiceren voor eigen automations.

Flash device.yaml en test één tegel tegelijk: juiste status, juiste fysieke actie, terugmelding vanuit HA en lange druk. Controleer ook dat externe wijzigingen in HA op het scherm verschijnen. Voer daarna de acceptatietest uit.

De iconfonts bevatten de tegeliconenset uit screen_manager/app/tile_icons.py; kies TILEn_ICON daaruit. Een ander icoon voeg je daar toe en draai je tools/generate_icons.py. De bundel bevat de fonts lokaal. De oudere uitgebreide TILE_CONFIGURATION.md beschrijft ook het oude scrollprofiel; gebruik die niet als hardware-/layoutinstructie voor dit bord.