One-window install: profile, wifi, USB flash and pairing hints (0.2.27)

"Nieuw scherm" used to span two dialogs plus a copy/download of the
installation YAML. It is now one dialog: board, name (node name derived,
editable), wifi only when secrets.yaml lacks it, the detected USB port,
and Installeren. The add-on writes the profile with unique API/OTA keys,
merges just the missing wifi lines into secrets.yaml (comments and other
secrets untouched, result re-parsed before writing), then builds and
flashes with the live ESPHome log and stage in the same dialog; a failed
build offers a retry without a second profile. The YAML download
endpoint is gone: the profile already lives in the ESPHome folder.

Pairing happens in Home Assistant itself, so the done view and a sidebar
card per not-yet-paired profile say so, with a button to Apparaten &
diensten, the API key to copy and the reminder to allow HA actions.
One profile per screen; the dialog says that too.

Tests: wifi merge cases, install pre-checks, pending list, profile
metadata; the date-anchored hourly forecast test now follows the clock.
Firmware 0.2.22 stays current.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

docs/EASY_SETUP.md

@@ -33,42 +33,41 @@ Deze app bevat de geteste ESPHome 2026.6.2-CLI en draait binnen je HA-aanmelding
 Een tweede ESPHome-beheerpagina, MQTT, blueprint of long-lived token is niet nodig.
 Gebruik de GitHub-versie voor updates; een lokale test-add-on is een andere app.
 
-## 2. Maak en bewaar je eigen apparaatprofiel
-
-Klik **Nieuw scherm**. Kies CYD of Guition, een herkenbare naam en een unieke
-apparaatnaam, bijvoorbeeld `scherm-keuken`. Klik **Bewaar profiel in ESP Screens**.
-
-De wizard controleert de bestaande ESPHome `secrets.yaml`. Met `wifi_ssid` en
-`wifi_password` aanwezig hoef je geen wifi in te vullen. Alleen als er nog geen
-secretsbestand is, vraagt de wizard je 2,4GHz-wifi eenmalig. Een bestaand bestand
-met ontbrekende of ongeldige wifi-sleutels moet je eerst herstellen; het wordt
-niet stilzwijgend overschreven.
-
-Je apparaat-YAML bevat unieke API- en OTA-sleutels. Bewaar dit profiel en gebruik
-het opnieuw bij updates. Voor een bestaand scherm telkens een nieuw profiel
-maken genereert nieuwe sleutels en is niet de updateroute.
-
-Wil je ESPHome Device Builder gebruiken, kies dan **Maak installatie-YAML** en
-kopieer/download die YAML naar een eigen apparaat daar. Beide routes gebruiken
-dezelfde firmwarepakketten. Wifi blijft in ESPHome `secrets.yaml`; API- en
-OTA-sleutels staan in het eigen apparaatprofiel.
-
-## 3. Eerste flash via USB op de Raspberry
+## 2. Nieuw scherm: aansluiten en installeren
 
 1. Sluit het scherm met een **USB-datakabel** aan op de machine waarop Home
-   Assistant draait. Bij meerdere borden: identificeer eerst de juiste poort,
-   of sluit ze voor de eerste installatie één voor één aan.
-2. Open **Firmware & USB** in ESP Screens en kies het zojuist bewaarde profiel.
-3. Kies bij **Installeren naar** de USB-poort van dit scherm.
-4. Klik **Bouwen & installeren** en wacht op een geslaagde build én upload.
-   De eerste build kan op een Raspberry meerdere minuten duren.
-5. Het scherm herstart en verbindt met wifi. Latere firmware-updates kunnen via
-   **Wifi / OTA** in dezelfde pagina, met het bestaande profiel.
+   Assistant draait. Bij meerdere borden: sluit ze voor de eerste installatie
+   één voor één aan, of controleer welke poort bij dit scherm hoort.
+2. Klik **Nieuw scherm**. Kies CYD of Guition en geef het scherm een naam,
+   bijvoorbeeld `Keuken`. De apparaatnaam (`keuken`) volgt daaruit; met
+   **aanpassen** kies je een andere.
+3. Wifi: staan `wifi_ssid` en `wifi_password` al in de ESPHome `secrets.yaml`,
+   dan gebruikt het scherm die automatisch. Ontbreken ze, of bestaat het bestand
+   nog niet, dan vraagt het venster ze eenmalig en zet ESP Screens alleen de
+   ontbrekende regels in `secrets.yaml`; commentaar en andere secrets blijven
+   staan. Een `secrets.yaml` die geen geldige YAML is, herstel je eerst zelf.
+4. Kies bij **Installeren via** de USB-poort van dit scherm en klik
+   **Installeren**. ESP Screens bewaart het profiel (`keuken.yaml`, met unieke
+   API- en OTA-sleutels) in de ESPHome-map, bouwt de firmware en schrijft die
+   via USB. Het ESPHome-log en de fase (bouwen, schrijven) staan in hetzelfde
+   venster; een eerste build duurt op een Raspberry enkele minuten. Je mag het
+   venster sluiten: de installatie loopt door en staat bij heropenen weer klaar.
+5. Na **Klaar** toont het venster de API-sleutel met een kopieerknop en de
+   koppelstappen uit hoofdstuk 3. Mislukt de build, dan staat het log open en
+   kun je **Opnieuw proberen**.
 
-Een USB-kabel aan je laptop is niet zichtbaar als USB-poort van de Raspberry.
-Gebruik voor die route de ESPHome-CLI op de laptop met je eigen profiel, of de
-browserinstallatie van ESPHome Device Builder. De stappen hierboven gebruiken
-uitsluitend ESP Screens op de HA-machine.
+Elk scherm krijgt zijn eigen profiel: vier schermen betekent vier keer **Nieuw
+scherm** met vier verschillende namen. Het gedeelde bordpakket is voor alle
+schermen gelijk; het profiel bevat alleen naam, sleutels en de wifi-verwijzing.
+Bewaar dat profiel en gebruik het opnieuw bij updates. Voor een bestaand scherm
+opnieuw **Nieuw scherm** doorlopen maakt nieuwe sleutels aan en is niet de
+updateroute.
+
+Geen USB-poort in de lijst? Een kabel aan je laptop is niet zichtbaar voor de
+Raspberry. Kies dan **Later · alleen het profiel bewaren**: het profiel staat
+daarna in dezelfde map die ESPHome Device Builder gebruikt, dus je kunt het daar
+openen en vanuit je browser flashen (**Install → Plug into this computer**), of
+het later via **Firmware & USB** alsnog aan de HA-machine installeren.
 
 **CYD:** bij de eerste start verschijnt de kalibratie. Tik het zichtbare kruisje
 drie keer rustig aan, houd elke tik kort vast en volg steeds het volgende kruisje.
@@ -80,19 +79,26 @@ je later opnieuw meten. Voor diagnose en de oudere handmatige installatie:
 
 **Guition:** de GT911-touchmapping zit in het bordprofiel; er is geen ADC-kalibratie.
 
-## 4. Koppel het scherm aan Home Assistant
+## 3. Koppel het scherm aan Home Assistant
+
+Dit gebeurt in Home Assistant zelf, buiten ESP Screens. Zolang een profiel nog
+niet aan Home Assistant is toegevoegd, staat het links onder **Mijn schermen**
+als kaart *nog niet in Home Assistant*, met de knop **Open Apparaten & diensten**
+en **Kopieer API-sleutel**; het klaar-scherm van **Nieuw scherm** heeft dezelfde
+knop. De kaart verdwijnt zodra het scherm in de lijst staat.
 
 1. Open **Instellingen → Apparaten & diensten**. Voeg het ontdekte ESPHome-apparaat
    toe. Niet ontdekt? Voeg de integratie **ESPHome** handmatig toe met het IP-adres
-   uit de ESPHome-logs, poort 6053.
-2. Vraagt HA om een encryptiesleutel? Kopieer de waarde van **api → encryption → key**
-   uit je eigen YAML. Gebruik niet het OTA-wachtwoord.
+   van het scherm, poort 6053.
+2. Vraagt HA om een encryptiesleutel? Plak de API-sleutel die het venster na de
+   installatie toont (ook terug te vinden als **api → encryption → key** in het
+   profiel). Gebruik niet het OTA-wachtwoord.
 3. Open bij de ESPHome-integratie **Configureren** en zet **Allow the device to
    perform Home Assistant actions** aan. Zonder deze toestemming verschijnen
    waarden wel, maar kan het scherm lampen en apparaten niet bedienen.
 4. Open ESP Screens. Het scherm verschijnt binnen ongeveer 30 seconden.
 
-## 5. Kies en wijzig je tegels
+## 4. Kies en wijzig je tegels
 
 Tip: zet in je ESPHome-YAML onder `wifi:` de regel `power_save_mode: none` (nieuwe
 wizard-YAML's hebben hem al); het scherm hangt aan het lichtnet en reageert dan zonder
@@ -145,7 +151,7 @@ totdat de gegevens opnieuw ontvangen zijn.
 Je mag indelingen opslaan terwijl een scherm offline is. De app verstuurt ze
 zodra het scherm terugkomt. De app moet blijven draaien voor actuele tegeldata.
 
-## 6. Updates zonder je instellingen kwijt te raken
+## 5. Updates zonder je instellingen kwijt te raken
 
 | Wat verandert? | Wat doe je? | Wat blijft behouden? |
 | --- | --- | --- |

docs/RELEASING.md

@@ -177,6 +177,20 @@ staan iconen in de browser uit het midden); draai daarna `generate_packages.py`.
 De substituties `MDI_GLYPH_*` zijn vervallen: `TILEn_ICON` in handmatige
 profielen moet uit de set komen. Geen gewijzigde preferences of sleutels.
 
+### Compatibiliteit 0.2.27 (firmware 0.2.22 blijft)
+
+Alleen de app. `POST /api/install` (YAML-download) is verwijderd; `POST
+/api/firmware/profiles` schrijft het profiel, vult ontbrekende wifi-sleutels in
+`secrets.yaml` aan (alleen de ontbrekende regels, geverifieerd door het resultaat
+opnieuw te parsen; een ongeldig bestand blijft onaangeraakt) en start met `target`
+(een gemelde USB-poort) direct `install`. Poort en bouwslot worden vóór het
+schrijven gecontroleerd. Het antwoord bevat `api_key`; de pagina toont hem eenmalig
+voor de HA-koppeling. Het jobobject krijgt `stage` (`config`, `compile`, `upload`).
+`profile_meta` levert extra `screen` (profiel gebruikt het bordpakket van dit
+project) en `api_key`; `/api/inventory` krijgt de additieve lijst `pending` met
+zulke profielen zonder gekoppeld scherm. Opslag, protocol, preferences en sleutels
+ongewijzigd.
+
 ### Compatibiliteit 0.2.26 / firmware 0.2.22
 
 Opslagversie en tegelprotocol blijven 1. Het layoutbericht krijgt het additieve veld

docs/TEST_RESULTS_0227.md

@@ -0,0 +1,59 @@
+# Testresultaten app 0.2.27 (2026-09-14, firmware 0.2.22 blijft)
+
+Alleen de app: "Nieuw scherm" is één venster van aansluiten tot flash, ontbrekende
+wifi gaat in `secrets.yaml`, en de koppeling in Home Assistant (buiten de add-on)
+is zichtbaar gemaakt met een knop en een kaart per nog niet gekoppeld profiel.
+
+## Geautomatiseerd
+
+- Python: 84 tests OK (`.venv-portal`, aiohttp 3.13.3, libyaml). Nieuw of aangepast:
+  - `test_wifi_reuse`: ontbrekende `wifi_ssid`/`wifi_password` worden aangevuld met
+    behoud van commentaar en andere secrets (ook een lege `wifi_ssid: ""` wordt
+    vervangen, niet gedupliceerd; waarden met `: `, `\` en `"` overleven de
+    round-trip); een ongeldig `secrets.yaml` blijft onaangeraakt en er komt dan geen
+    profiel; `install()` weigert een onbekende poort en een bezet bouwslot vóór er
+    iets geschreven is; `profile_names()` herkent eigen profielen (`screen`) en levert
+    de API-sleutel, een handmatig ESPHome-profiel niet.
+  - `test_portal`: `POST /api/firmware/profiles` met een onbekende `target` geeft 400
+    zonder profiel; zonder `target` maakt het profiel en geeft `api_key` (32 bytes)
+    zonder job; `/api/inventory?light=1` toont het profiel in `pending` met
+    `installed: false`; `/api/firmware` lekt de wifi-waarden niet.
+  - `test_updates`: metadata-cache met de extra velden.
+  - `test_rich_cards.HourlySync` was datumgebonden (vaste 13 september) en faalde
+    sinds 14 september op main; de uurvoorspelling in de managertest volgt nu de
+    echte klok.
+- `py_compile` van de add-on; `node --check` van `app.js`.
+
+## In de browser (in-app browser tegen de echte server, nep-CLI)
+
+`server.py` in `SCREEN_DEV`-modus met een nep-`esphome` op het pad (schrijft
+compile-/uploadregels, faalt op een vlag) en een nep-USB-poort (`Firmware.ports`
+gepatcht). Doorlopen en per stap bekeken:
+
+- Nieuw venster: bordkeuze, naam → apparaatnaam (`Keuken Guition` → `keuken-guition`),
+  wifi-velden zichtbaar zolang `secrets.yaml` ontbreekt; na de eerste installatie
+  "Wifi komt uit je ESPHome secrets.yaml" en geen velden meer. `secrets.yaml` bevat
+  daarna precies `wifi_ssid`/`wifi_password` (0600), het profiel het bordpakket.
+- Installeren via USB: fase "Firmware bouwen…" → "Firmware naar … schrijven…" (uit
+  `job.stage`), log inklapbaar, daarna "Klaar." met API-sleutel, kopieerknop, de
+  vier koppelstappen en de knop **Open Apparaten & diensten**; CYD-tekst noemt de
+  kalibratie, Guition niet.
+- Mislukte build: "Installeren mislukt", log open met de foutregel, **Opnieuw
+  proberen** herstart alleen de job (geen tweede profiel) en slaagt na het weghalen
+  van de vlag.
+- Zonder poort: "Later · alleen het profiel bewaren", knop "Profiel bewaren",
+  klaar-scherm met de vervolgroutes.
+- Zijbalk: per niet-gekoppeld profiel een kaart ("geïnstalleerd, maar nog niet in
+  Home Assistant" voor een in deze sessie geflasht profiel, anders "nog niet in Home
+  Assistant … Firmware & USB → bestand"), met **Open Apparaten & diensten** (navigeert
+  het bovenste venster naar `/config/integrations/dashboard`; op de dev-server een
+  404, in HA de integratiepagina) en **Kopieer API-sleutel**.
+
+## Nog niet geverifieerd
+
+- De echte ESPHome-CLI en USB-detectie (`/dev/serial/by-id`) in de add-on-container
+  op de Yellow, en de eerste echte flash via dit venster.
+- Of de knop **Open Apparaten & diensten** vanuit het HA-ingress-iframe naar de
+  integratiepagina springt (zelfde origin, dus verwacht wel).
+- Of Home Assistant het scherm na de flash ontdekt en de kaart in de zijbalk
+  verdwijnt zodra `Tegelinstellingen` in het register staat.