Add Home Assistant screen manager and runtime tile configuration
This commit is contained in:
Max Gramser
@@ -0,0 +1,164 @@
|
||||
# Een nieuw scherm, van USB naar dagelijks gebruik
|
||||
|
||||
Met **ESP Screen Manager** kies je je tegels in Home Assistant. Je zoekt op
|
||||
naam, apparaat, ruimte of entity-ID, zet ze in de gewenste volgorde en klikt
|
||||
op **Opslaan & naar scherm**. Daarna blijft de status automatisch actueel.
|
||||
Je hoeft voor andere tegels **niet opnieuw te flashen**.
|
||||
|
||||
Dit werkt met Home Assistant OS op een 64-bits Raspberry Pi of een amd64-machine,
|
||||
ESPHome Device Builder en een van deze exacte schermvarianten:
|
||||
|
||||
| Keuze | Hardware |
|
||||
| --- | --- |
|
||||
| CYD | ESP32-2432S028, 320×240, ILI9341 en XPT2046 |
|
||||
| Guition | ESP32-S3-4848S040, 480×480, ST7701S en GT911 |
|
||||
|
||||
Andere schermen met ongeveer dezelfde naam kunnen andere pinnen hebben. Gebruik
|
||||
het bordprofiel dat bij de hardware hoort. Gebruik een USB-kabel die data ondersteunt.
|
||||
De wallbox-relais worden niet gebruikt.
|
||||
|
||||
## 1. Installeer de twee apps
|
||||
|
||||
1. Open **Instellingen → Apps → Installeer een app** (in oudere HA-versies:
|
||||
**Instellingen → Add-ons → Add-onwinkel**).
|
||||
2. Installeer **ESPHome Device Builder**, start deze en zet hem in de zijbalk.
|
||||
Gebruik ESPHome **2026.6.2 of nieuwer**. De release is met 2026.6.2 getest.
|
||||
3. Open in de appwinkel het menu rechtsboven → **Repositories**. Voeg toe:
|
||||
`https://github.com/MaxGramser/homeassistant_espscreen`.
|
||||
4. Zoek **ESP Screen Manager**, installeer en start deze. Zet **Starten bij
|
||||
opstarten** en **Tonen in zijbalk** aan. Open de webinterface.
|
||||
|
||||
De beheerpagina draait binnen Home Assistant en gebruikt je HA-aanmelding.
|
||||
Je hoeft geen extra gebruiker, MQTT, blueprint of long-lived token in te stellen.
|
||||
Installeer voor normaal gebruik de GitHub-versie: een handmatig gekopieerde lokale
|
||||
test-add-on ontvangt geen updates uit GitHub.
|
||||
|
||||
## 2. Download je eigen installatie-YAML
|
||||
|
||||
Klik in ESP Screens op **Nieuw scherm**. Kies CYD of Guition, een herkenbare naam
|
||||
en een unieke apparaatnaam zoals `scherm-keuken`. Klik **Maak installatie-YAML**. Gebruik **Kopieer YAML** om de tekst meteen in
|
||||
ESPHome te plakken, of **Download bestand**. Op een HTTP-verbinding kan Chrome
|
||||
downloads blokkeren; de kopieeroptie blijft bruikbaar.
|
||||
|
||||
Dit bestand bevat unieke API- en OTA-sleutels. Bewaar het. Maak voor ieder nieuw
|
||||
scherm een nieuw bestand. Download voor een bestaand scherm niet telkens een nieuw
|
||||
bestand: daarmee zou je nieuwe sleutels genereren.
|
||||
|
||||
Open **ESPHome Device Builder → Secrets** en vul eenmaal je 2,4GHz-wifi in:
|
||||
|
||||
```yaml
|
||||
wifi_ssid: "Jouw wifi"
|
||||
wifi_password: "Jouw wifiwachtwoord"
|
||||
```
|
||||
|
||||
Andere bestaande secrets mogen blijven staan. Gebruik geen gedeelde API-sleutel
|
||||
voor alle nieuwe schermen; de gedownloade YAML bevat al een eigen sleutel.
|
||||
|
||||
## 3. Eerste flash via USB op de Raspberry
|
||||
|
||||
1. Klik in ESPHome op **New device**, gebruik dezelfde unieke naam en sla de
|
||||
directe installatie over. Kies zo nodig ESP32 als tijdelijke wizardkeuze.
|
||||
2. Klik **Edit** bij het nieuwe apparaat. Vervang de **hele inhoud** door je
|
||||
gedownloade YAML en sla op. Het pakket levert zelf de juiste hardwareconfiguratie.
|
||||
3. Sluit het scherm met USB aan op de Raspberry waarop Home Assistant draait.
|
||||
4. Klik **Install → Plug into the computer running ESPHome Device Builder**.
|
||||
Kies de USB-seriële poort van dit scherm. Bij meerdere schermen: sluit ze voor
|
||||
de eerste installatie één voor één aan.
|
||||
5. Wacht op een geslaagde build én upload. De eerste build kan op een Raspberry
|
||||
lang duren. Laat deze afronden. Het scherm maakt daarna verbinding met wifi.
|
||||
|
||||
Een browseroptie **Plug into this computer** bedoelt de computer waarop je browser
|
||||
draait, niet de Raspberry. Kies die alleen wanneer het scherm aan die computer zit.
|
||||
|
||||
**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.
|
||||
Er zijn vijf posities. Het midden controleert de nauwkeurigheid. Bij een mislukte
|
||||
meting vraagt het scherm opnieuw te beginnen. De correctie wordt lokaal opgeslagen
|
||||
en blijft bij OTA-updates behouden. Via de HA-apparaatknop **Touch kalibreren** kun
|
||||
je later opnieuw meten. Voor diagnose en de oudere handmatige installatie:
|
||||
[CALIBREREN.md](CALIBREREN.md).
|
||||
|
||||
**Guition:** de GT911-touchmapping zit in het bordprofiel; er is geen ADC-kalibratie.
|
||||
|
||||
## 4. Koppel het scherm aan Home Assistant
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
Selecteer je scherm, vul de titel in en zoek entiteiten. Je kunt maximaal tien
|
||||
tegels toevoegen. Sleep om te ordenen of gebruik de pijltjes. Je kunt iedere tegel
|
||||
een korte eigen naam geven. Klik **Opslaan & naar scherm**.
|
||||
|
||||
- Lamp, switch, input_boolean en fan: tik om aan/uit te zetten.
|
||||
- Lamp lang indrukken: helderheid, regenboogkleur en wittemperatuur, voor zover
|
||||
de lamp die functies ondersteunt.
|
||||
- Climate, vacuum en cover: tik om de bedieningskaart te openen.
|
||||
- Fan lang indrukken: snelheid als het apparaat percentages ondersteunt.
|
||||
- Scene/script: tik om uit te voeren; button/input_button: tik om in te drukken.
|
||||
- Sensor/binary_sensor/input_select: toont de waarde, voert geen actie uit.
|
||||
|
||||
Er staan zes tegels op een pagina. Bij maximaal zes verdwijnen Vorige/Volgende.
|
||||
De standby-tijd is standaard tien minuten. Bij offline apparaten blokkeert het
|
||||
scherm acties. Als de app/HA langer dan circa 95 seconden geen updates geeft,
|
||||
wordt de bediening geblokkeerd 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
|
||||
|
||||
| Wat verandert? | Wat doe je? | Wat blijft behouden? |
|
||||
| --- | --- | --- |
|
||||
| Andere entiteiten, namen of volgorde | Opslaan in ESP Screens | Wifi, sleutels, kalibratie |
|
||||
| Nieuwe beheerpagina/appversie | Appwinkel → ESP Screen Manager → Update | Alle indelingen in `/data/screens.json` |
|
||||
| Nieuwe schermfunctie/kaart | ESPHome → bestaand apparaat → Install → Wirelessly | Eigen YAML, sleutels en CYD-kalibratie; app stuurt tegels opnieuw |
|
||||
|
||||
De eigen YAML verwijst naar de firmwarepakketten in `main`. Bij een nieuwe build
|
||||
haalt ESPHome de nieuwste gepubliceerde pakket- en componentcode op. Je vervangt
|
||||
je eigen YAML dus niet door een nieuw downloadbestand. Wifi, naam en sleutels
|
||||
staan buiten het gedeelde pakket en blijven gelijk.
|
||||
|
||||
Maak vóór updates een Home Assistant-back-up inclusief ESP Screen Manager en
|
||||
ESPHome Device Builder. **Verwijderen/herinstalleren** van een app is niet hetzelfde
|
||||
als updaten; daarmee kun je de gegevensmap wissen. Houd de apparaatnaam en de
|
||||
entity-ID van **Tegelinstellingen** gelijk, zodat de bestaande indeling gekoppeld blijft.
|
||||
|
||||
Voor een nieuwe ondersteunde kaart update je eerst de app, daarna de firmware.
|
||||
De beheerder moet protocol- en gegevensmigraties achterwaarts compatibel maken;
|
||||
zie [RELEASING.md](RELEASING.md). Voor terugrollen kun je `ref: main` in je eigen
|
||||
YAML tijdelijk vervangen door een eerdere releasetag, zonder de sleutels te wijzigen.
|
||||
|
||||
## Als iets niet werkt
|
||||
|
||||
- **Geen scherm in de lijst:** controleer of de nieuwe Easy Setup-firmware draait,
|
||||
de ESPHome-integratie verbonden is en de tekstentiteit **Tegelinstellingen**
|
||||
niet uitgeschakeld is. De oude handmatige firmware publiceert die standaard niet.
|
||||
- **Wel tegels, geen acties:** geef het apparaat toestemming voor HA-acties.
|
||||
- **Niet beschikbaar:** controleer of de geselecteerde entiteit in HA bestaat en
|
||||
beschikbaar is. Een hernoemde entity-ID moet je opnieuw kiezen.
|
||||
- **Geen OTA:** controleer wifi/IP en het oorspronkelijke OTA-wachtwoord. Gebruik
|
||||
zo nodig dezelfde eigen YAML via USB. Genereer geen nieuwe identiteit.
|
||||
- **Build mislukt:** lees de eerste fout, controleer ESPHome-versie en internet voor
|
||||
GitHub/fontdownloads. Gebruik bij te weinig Raspberry-geheugen tijdelijk een
|
||||
krachtigere computer voor compileren; de YAML blijft hetzelfde.
|
||||
- **Bestaand handmatig scherm migreren:** bewaar de oude YAML en neem de bestaande
|
||||
apparaatnaam, API-sleutel en OTA-wachtwoord over in het nieuwe installatieprofiel.
|
||||
Kies daarna de tegels in de app. De oude vaste tegel-substituties worden niet
|
||||
automatisch in de nieuwe beheerpagina geïmporteerd.
|
||||
|
||||
HA Container zonder Supervisor heeft geen appwinkel. Deze installatiehandleiding
|
||||
richt zich op Home Assistant OS; de ontwikkelserver is geen productieroute voor
|
||||
een los openbaar portal.
|
||||
|
||||
Gebruikte HA-mechanismen: [Ingress](https://developers.home-assistant.io/docs/apps/presentation/),
|
||||
[interne HA-API](https://developers.home-assistant.io/docs/apps/communication/) en
|
||||
[ESPHome-pakketten](https://esphome.io/components/packages/).
|
||||
@@ -0,0 +1,58 @@
|
||||
# Updates publiceren zonder gebruikersconfiguratie te vervangen
|
||||
|
||||
## Indeling van de code en gegevens
|
||||
|
||||
- `main` is de distributiebranch voor de app **en beide** firmwarepakketten.
|
||||
De Guition-branch blijft beschikbaar voor bordwerk; publiceer gedeelde releases
|
||||
altijd ook naar main.
|
||||
- `screen_manager/config.yaml` bevat de appversie. Verhoog die bij iedere apprelease.
|
||||
Git push alleen is niet genoeg om een bestaande app een update aan te bieden.
|
||||
- De appimage bevat uitsluitend code. Indelingen leven in `/data/screens.json`
|
||||
(`version: 1`, `screens: {...}`). Een update/herbuild behoudt deze volumegegevens.
|
||||
- De eigen ESPHome-YAML bevat naam, wifi-verwijzingen en unieke API/OTA-sleutels.
|
||||
Gedeelde pakketten bevatten geen secrets, vaste eigenaarsentiteiten of wifi.
|
||||
- CYD-kalibratie staat in ESP32-preferences. Behoud de preference-key, structuur
|
||||
en partitie-indeling, of schrijf een expliciete migratie.
|
||||
- Het tegelprotocol gebruikt `v: 1`. Houd oudere velden en domeinen bruikbaar.
|
||||
Een gewijzigde opslagversie moet een geteste migratie met back-up krijgen.
|
||||
De app weigert onbekende versies in plaats van de data leeg te overschrijven.
|
||||
|
||||
## Voor elke release
|
||||
|
||||
1. Pas de bronprofielen en gedeelde componenten aan. Draai
|
||||
`python3 tools/generate_packages.py`; bewerk `packages/*.yaml` nooit rechtstreeks.
|
||||
2. Draai alle Python-tests met aiohttp geïnstalleerd, alle `tests/*.cpp`, de
|
||||
generator met `--check`, en compileer beide Easy Setup-profielen plus de
|
||||
bestaande handmatige profielen. Controleer dat er geen secrets in Git staan.
|
||||
3. Test appstart, opslaan, opnieuw starten/updaten met bestaande indelingen,
|
||||
opnieuw verbinden met HA en een ESP-herstart. Test een nieuwe kaart op echte
|
||||
hardware. Een goede build vervangt fysieke touchacceptatie niet.
|
||||
4. Verhoog appversie en firmwareprojectversie; schrijf CHANGELOG en concrete
|
||||
testresultaten. Publiceer alleen compatibele wijzigingen rechtstreeks op main.
|
||||
5. Commit en push main. Maak een onveranderlijke tag `screens-vX.Y.Z` van dezelfde
|
||||
commit. Werk de Guition-branch bij. Test de remote YAML in een lege map:
|
||||
alle componenten/fonts moeten via GitHub kunnen worden opgehaald.
|
||||
6. De gebruiker controleert de appwinkel op updates en update ESP Screen Manager.
|
||||
Voor nieuwe schermfuncties: bestaand ESPHome-apparaat → Install → Wirelessly.
|
||||
De bestaande YAML blijft staan; `refresh: 0s` haalt bij elke build actuele code.
|
||||
|
||||
## Lokale ontwikkeling
|
||||
|
||||
Kopieer alleen `screen_manager/` naar de gedeelde `addons/esp_screen_manager/`.
|
||||
Herlaad de appwinkel, installeer de lokale versie en bouw na codewijzigingen opnieuw.
|
||||
Een lokale testversie heeft een andere add-onidentiteit dan de GitHub-versie; de
|
||||
gegevens verhuizen niet automatisch. Test voor de uiteindelijke installatie de
|
||||
GitHub-versie en zet de lokale versie uit om twee schrijvers te voorkomen.
|
||||
|
||||
Voor backendtests op een ontwikkelcomputer:
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv-portal
|
||||
.venv-portal/bin/pip install aiohttp PyYAML
|
||||
.venv-portal/bin/python -m unittest discover -s tests
|
||||
```
|
||||
|
||||
Een tijdelijke ontwikkelserver ondersteunt `SCREEN_DEV=1`, `HA_API` (eindigt op
|
||||
`/api`), `HA_TOKEN_FILE` en `SCREEN_DATA`. Hij bindt alleen op localhost. Zet een
|
||||
token nooit in broncode, URL's of Git. Productie gebruikt Supervisor en accepteert
|
||||
alleen het Ingress-proxyadres; er is geen extra publieke poort.
|
||||
Reference in New Issue
Block a user