Max Gramser
517b102786
Any tile can now be double width: pack() in runtime_model.h places wide tiles in the left column and the manager preview follows the same rules. New cards: built-in clock (digital or analog, screen.clock), five-day weather forecast on a wide weather card fed by weather.get_forecasts, history sparkline for sensors, sunrise/sunset (sun.sun), live kitchen timer (timer.*, tap starts or pauses) and presence (person.*). The manager pre-computes time-zone and forecast extras in a new 'x' object and refuses layouts with new domains until the screen runs 0.2.14. The self-test follows the packing, checks custom card parts and wide widths, and diagnostics/send_layout.py pushes a demo layout of every card type for render checks without Home Assistant. App 0.2.12, firmware 0.2.14. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
144 lines
8.2 KiB
Markdown
144 lines
8.2 KiB
Markdown
# 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. Doe dat na elkaar: profielen met dezelfde
|
|
`DEVICE_NAME` delen één build-map, en een parallelle build laat een upload
|
|
het verkeerde `firmware.bin` kiezen. 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.
|
|
|
|
|
|
### Instellingencompatibiliteit 0.1.2
|
|
|
|
`settings` is een optioneel object binnen een schermindeling en binnen het bestaande
|
|
`v: 1, op: layout`-bericht. Een ontbrekend object behoudt eerder gedrag. Oude
|
|
firmware negeert dit extra veld en blijft tegels ontvangen. De beheerpagina meldt
|
|
dat nieuwe firmware nodig is. Een oude browser die alleen tegels opslaat, wist
|
|
opgeslagen instellingen niet. Onbekende instellingen worden geweigerd.
|
|
|
|
Firmware gebruikt een afzonderlijke preferences-key `0x53435231` met een vaste
|
|
versie-1 structuur (elf int32-velden en een uint32-versie). Wijzig key, structuur
|
|
of versie niet zonder migratie. Alleen gewijzigde instellingen worden opgeslagen;
|
|
periodieke herhaling veroorzaakt geen flashwrites en geen nieuwe idle-timer.
|
|
|
|
### Compatibiliteit 0.2.0
|
|
|
|
Opslagversie en tegelprotocol blijven 1. Optionele `tiles[].options`, `o` in
|
|
statusberichten, `history` en `inbox` in het layoutbericht zijn additief. Een
|
|
oudere browser die opties niet meestuurt behoudt de bestaande opties voor dezelfde
|
|
entiteit. Oudere firmware negeert extra velden. Nieuwe entiteitsdomeinen vereisen
|
|
wel firmware 0.2.0; bij terugrollen naar een oudere app eerst de gegevensback-up
|
|
herstellen, omdat die app nieuwe domeinen nog niet kan laden. Geen oude opslag
|
|
stilzwijgend overschrijven. Bestaande preference-keys blijven ongewijzigd.
|
|
|
|
De app gebruikt nu de officiële ESPHome-container, mapped `homeassistant_config`
|
|
naar `/homeassistant` en vraagt UART/USB voor de door de gebruiker gekozen poort.
|
|
Config/secrets blijven in de eigen HA-configmap; builds in `/data`. App-updates
|
|
vervangen deze mappen niet. Native getalinstellingen melden wijzigingen via
|
|
`esphome.screen_setting`; de manager valideert inbox, sleutel en waarde.
|
|
|
|
De ingebouwde CLI bewaart opnieuw te downloaden caches onder `/data/build` en
|
|
`/data/platformio`. Alleen deze mappen zijn uitgesloten van appback-ups via
|
|
`backup_exclude`. `/data/screens.json` en eigen ESPHome-configuraties blijven
|
|
back-upgegevens; sluit nooit `/data` als geheel uit.
|
|
|
|
### Compatibiliteit 0.2.7
|
|
|
|
Twintig runtime-tegels vereisen firmware 0.2.7+. De manager controleert die versie
|
|
voor opslaan en verzenden van grotere indelingen. Bestaande indelingen blijven
|
|
behouden bij oudere firmware. Oude appversies ondersteunen niet meer dan tien;
|
|
breng de indeling eerst terug tot tien of herstel hun gegevensback-up bij rollback.
|
|
`settings.swipe_pages` is additief in opslagversie 1. Op de draad staat het buiten
|
|
het ongewijzigde elfvelden-settingsobject. De bestaande preferences blijven gelijk;
|
|
alleen swipe gebruikt een nieuwe eigen uint32-key `0x53575031`, standaard uit.
|
|
|
|
### Compatibiliteit 0.2.9
|
|
|
|
Guition-rotatie is additief als `settings.rotation` in appdata, uitsluitend
|
|
0/90/180/270. Oude beheerpagina's die het veld weglaten behouden de opgeslagen
|
|
hoek. Op de draad staat `rotation` naast het ongewijzigde elfvelden-settingsobject.
|
|
De firmware bewaart de hoek als afzonderlijke uint32 op key `0x524F5431`; de
|
|
bestaande Settings-structuur en CYD-kalibratie blijven ongewijzigd. Alleen de
|
|
Guition activeert de rotatiecallback. De diagnostische entity `Guition schermtype`
|
|
maakt deze capability herkenbaar, ook als het scherm offline of hernoemd is.
|
|
|
|
### Compatibiliteit 0.2.10
|
|
|
|
`tiles[].options.background` is een optionele paletnaam binnen opslagversie 1.
|
|
Op de draad staat dit in het bestaande `o`-object. Oudere firmware negeert het
|
|
veld; nieuwe firmware valt bij onbekende namen terug op de normale kleuren.
|
|
De app accepteert uitsluitend het lichte palet uit `TILE_BACKGROUNDS`. Een oude
|
|
editor die `background` weglaat behoudt de opgeslagen kleur voor dezelfde entity;
|
|
expliciet `auto` herstelt de standaard. Geen gewijzigde voorkeurstructuur of
|
|
sleutels, geen nieuwe firmwareflash nodig voor latere kleurkeuzes.
|
|
|
|
Een oude apprelease van vóór 0.2.10 kent dit optieveld niet. Bij terugrollen van
|
|
de app herstel je daarom de bijbehorende gegevensback-up; wis of negeer geen
|
|
onbekende opties om een oud opslagbestand toch te openen.
|
|
|
|
### Compatibiliteit 0.2.12 / firmware 0.2.14
|
|
|
|
Opslagversie en tegelprotocol blijven 1. Additief: `tiles[].options.size`
|
|
(`single`/`wide`), nieuwe `display`-waarden (`forecast` voor weer, `graph` voor
|
|
sensoren, `digital`/`analog` voor `screen.clock`), de ingebouwde entity
|
|
`screen.clock` en de HA-domeinen `sun`, `timer` en `person`. Statusberichten
|
|
krijgen een optioneel object `x` met door de manager berekende waarden
|
|
(voorspellingsdagen, zontijden in de HA-tijdzone, timer-eindtijd als epoch).
|
|
Oudere firmware negeert `size`, nieuwe displays en `x`, maar weigert onbekende
|
|
domeinen in de hele indeling; de manager stuurt zo'n indeling daarom pas na
|
|
firmware 0.2.14 (`min_firmware`) en bewaart haar ondertussen. Voorspellingen
|
|
komen via `weather.get_forecasts` met `return_response`; zonder antwoord blijft
|
|
de weerkaart de gewone kaart. Geen gewijzigde preferences of sleutels.
|