WetterCubePlus/Entwicklung

Aufbau des Repositorys

Datei / Ordner	Inhalt
`WetterCubePlus.ino`	Hauptprogramm (WLAN, Datenabruf, UI-Befüllung, Web-Oberfläche, Rechner, Spiel)
`webui_html.h`	HTML der Web-Oberfläche und des Einrichtungsportals
`build_opt.h`	Compiler-Schalter (`-Os`, `LV_COLOR_16_SWAP`, `LV_MEM_SIZE`, `LV_MEM_PSRAM`)
`lv_conf.h.example`	LVGL-Konfiguration (als `lv_conf.h` in den Arduino-`libraries`-Ordner kopieren)
`partitions.csv`	eigene Partitionstabelle (2× 4 MB App, Rest SPIFFS)
`src/ui/`	PicoPixel-Export der Oberfläche (LVGL 8)
`WetterAmpel/`	Firmware des ESP32-C3-Zusatzgeräts
`docs/`	GitHub Pages: Web-Installer, `version.json`, `manifest.json`, `firmware/*.bin`
`screenshots/`	Fotos für die README und dieses Wiki
`bump_version.sh`, `deploy_ui.sh`	Hilfsskripte (siehe unten)
`CHANGELOG.md` / `CHANGELOG.en.md`, `DEVLOG.md`	Änderungen (zweisprachig) und Entwicklungs-Tagebuch

Bauen

Arduino IDE: Board ESP32S3 Dev Module, PSRAM OPI PSRAM, Flash Size 16 MB, Partition Scheme Custom. Bibliotheken: LovyanGFX (≥ 1.2), LVGL 8.3.x, ArduinoJson. Zusätzlich lv_conf.h bereitstellen (siehe Abschnitt „Manuelle Installation“ in der README).

Kommandozeile:

arduino-cli compile --fqbn "esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,PartitionScheme=custom,UploadSpeed=921600" .

Ohne diese Optionen meldet der Compiler fälschlich „Sketch zu groß“, weil dann die Standard-Partitionstabelle gilt.

Cache-Falle: Nach jeder Änderung an build_opt.h den Arduino-Sketch-Cache leeren (~/Library/Caches/arduino/sketches/…) und die IDE neu starten, sonst werden die neuen Schalter nicht übernommen. Doppelte Dateien: Liegt die Arduino-Bibliothek in einem iCloud-Ordner, entstehen manchmal Konfliktkopien wie datei 3.c. Sie führen zu „multiple definition“-Fehlern beim Linken und müssen gelöscht werden.

Speicher

Speicher	Verwendung
Interner RAM (ca. 320 KB nutzbar)	Variablen, Heap (WLAN, HTTPS/TLS braucht ca. 40–50 KB), Stacks
PSRAM (8 MB, langsamer)	LVGL-Speicher (`-DLV_MEM_PSRAM`), Zeichenpuffer, Radarbild, Spielfeld, große Downloads
Flash (16 MB)	Programm, Icons, Schriften, Einstellungen (NVS)

Der LVGL-Speicher liegt seit v1.3.0 im PSRAM. Das gab dem internen Heap etwa 130 KB zurück (tiefster Heap-Stand von 25 KB auf ca. 157 KB). Mit LV_MEM_PSRAM liefert lv_mem_monitor() keine Werte, der Sketch nutzt dann den freien PSRAM.

Partitionen (16 MB Flash):

Partition	Größe	Zweck
`nvs`	20 KB	Einstellungen (WLAN, Helligkeit, Bestenliste …), bleibt bei Updates erhalten
`otadata`	8 KB	merkt sich den aktiven App-Slot
`app0`, `app1`	je 4 MB	zwei Firmware-Plätze: das Update wird in den jeweils anderen geschrieben, dann wird umgeschaltet
`spiffs`	ca. 8 MB	reserviert, im Code nicht genutzt

Die Firmware belegt aktuell ca. 2,8 MB; im 4-MB-Slot bleiben rund 1,4 MB frei. Icons werden daher als 128×128 angelegt (ein 256er-Icon kostet 196 KB, ein 128er 49 KB). Die Partitionstabelle lässt sich nicht per Update ändern, nur per USB oder Web-Installer.

Oberfläche mit PicoPixel

In PicoPixel nach src/ui/ exportieren.
./deploy_ui.sh ausführen. Das Skript passt den Export an (LVGL-Include, Bilddateien .c → .inc, Farbfix 0xff, FADE_IN → NONE gegen einen Absturz, Sonderzeichen ²) und prüft, ob alle vom Sketch verwendeten Objekte noch existieren.
Nach jedem Export prüfen: PicoPixel nummeriert Button-Namen gelegentlich neu; die Verdrahtung (REG_CB) im Sketch muss zu den Namen passen.
Icons: neue Bilder als 128×128 hochladen und mit 83×83 anlegen; PicoPixel rechnet den Zoom aus Widget- und Bildgröße selbst. Zur Laufzeit gesetzte Icons brauchen einen eigenen Zoom (setWetterIcon() im Sketch).

Release-Ablauf

bash bump_version.sh X.Y.Z setzt die Version überall (Firmware, version.json, manifest.json, Webseite, README-Badges).
CHANGELOG.md und CHANGELOG.en.md ergänzen, außerdem DEVLOG.md.
In der Arduino IDE Sketch → Export Compiled Binary; die firmware.bin muss in docs/firmware/ liegen.
bash bump_version.sh --check prüft, dass alles konsistent ist und das Binary die Version enthält.
Vor dem Commit den Diff auf Zugangsdaten prüfen (das Repo ist öffentlich), dann committen, pushen, Tag vX.Y.Z setzen und ein GitHub-Release mit den vier Dateien bootloader.bin, boot_app0.bin, partitions.bin, firmware.bin anlegen.

Die Geräte holen version.json über raw.githubusercontent.com und die Firmware von GitHub Pages (docs/firmware/firmware.bin). Es gilt: Ein Gerät bietet nur höhere Versionsnummern an.

Lizenz und Credits

Der Quellcode steht unter der Apache-Lizenz 2.0 (siehe LICENSE und NOTICE; Versionen bis v2.1.2 stehen unter CC BY-NC 4.0), Texte, Bilder und die 3D-Druckdateien unter CC BY-NC 4.0 (LICENSE-Dokumentation.txt); die Wetter-Icons stammen von Meteocons (MIT, seit Version 1.6.5; früher Dovora), die Schrift ist Montserrat (SIL OFL 1.1), die Bedienelemente-Icons (Home, Zahnrad, Pfeile, Plus, Rechner, Spiel) von Icons8 Flat Color Icons (MIT oder Good Boy License); Details in CREDITS.md.