Fusion/Entwicklung

Aufbau des Repositorys

Datei / Ordner	Inhalt
`CMakeLists.txt`, `main/`	ESP-IDF-Projekt; `main/main.cpp` ist der Einstieg (`app_main()`: NVS starten, dann `starten()` aus `src/app/app.cpp`); `src/platform/` ist die kleine Ersatzschicht für die früheren Arduino-Namen
`sdkconfig.defaults`, `sdkconfig.defaults.esp32s3`, `sdkconfig.defaults.esp32p4`	gemeinsame und chip-spezifische Einstellungen (P4-Entwurf, noch ohne Board erprobt)
`partitions.csv`, `partitions_p4.csv`	Partitionstabellen (S3: 16 MB Flash, 2 × knapp 8 MB OTA-Slots; P4: 32 MB, 2 × 10 MB)
`conf/lv_conf.h`	LVGL-Konfiguration (Projektkopie)
`src/board/`, `src/hardware/`, `src/display/`	Board-Schicht (`board.h`; `board/s3/` RGB-Panel, I²C, IO-Erweiterung, SD über SPI; `board/p4/` MIPI-DSI, PWM-Helligkeit, SDMMC), gemeinsamer Touch-Treiber GT911 und LVGL-Anbindung
`src/app/`	Navigation, Daten (`data_.cpp`), Oberfläche (`ui_.cpp`), WebUI, Update (`ota.cpp`), Netzwerk-Task (`app.cpp`), Home Assistant (`homeassistant.cpp`), animierte Wettersymbole (`wetteranim.cpp`, nur P4)
`src/sensors/`	Sensoren (intern und MQTT), Schalter-Kacheln (`schalter*.cpp`), MQTT-Client
`src/ui/`	PicoPixel-Export der Oberfläche (LVGL 8, 1024×600)
`tools/`	`deploy_ui.sh`, `icons_code.py`, `wetter_icons.py`, `anim_pack.py`, `flash_usb.py`, `notfall_snap.py`
`assets/`	Logo, Roadmap-Grafik, Teaser, Icons (`icons/wetter/`: 32 Wettersymbole; `icons/meteocons/`: Sensor- und Mond-Icons als PNG; `icons/anim/`: Animationspaket für den P4)
`docs/`	GitHub Pages: Web-Installer, `version.json`, `manifest.json`, `firmware/*.bin`
`CHANGELOG.md` / `CHANGELOG.en.md`	Änderungen (zweisprachig)

Bauen

ESP-IDF 5.5.x installieren (git clone --branch v5.5.5 --recursive https://github.com/espressif/esp-idf.git ~/esp/esp-idf-v5.5.5 && cd ~/esp/esp-idf-v5.5.5 && ./install.sh esp32s3,esp32p4), dann:

bash build.sh                       # bauen (Ziel esp32s3; beim ersten Mal lädt der Komponentenmanager LVGL, ArduinoJson und mdns)
bash build.sh flash /dev/cu.xxx     # bauen und flashen (Port aus ls /dev/cu.*)
bash build.sh recovery              # Notfall-App bauen (recovery/build/recovery.bin), vor dem Flashen
bash build.sh clean                 # nach Änderungen an sdkconfig.defaults*
PCLK=40 bash build.sh               # Pixeltakt in MHz (S3: Standard 30 = 33 Bilder/s; bei 15 MHz = 16 Hz flimmert das Panel sichtbar, zu hohe Takte geben Streifen, wenn WLAN, Web-Oberfläche und Display zugleich den PSRAM brauchen)
TARGET=esp32p4 bash build.sh        # P4-Board (Ordner build_p4; noch ohne Board erprobt), ebenso `TARGET=esp32p4 bash build.sh recovery`

Wichtige Einstellungen auf dem S3 (sdkconfig.defaults.esp32s3): Flash und PSRAM 120 MHz, Programmcode im PSRAM, LCD_RGB_ISR_IRAM_SAFE (das Bild läuft beim Flash-Schreiben weiter), 64-KB-Daten-Cache, TLS-Puffer im PSRAM, WLAN- und LWIP-Puffer im internen RAM (im PSRAM stehlen sie dem Display Bandbreite, es gibt Streifen), WLAN-Code ohne IRAM-Optimierung (spart ca. 15 bis 20 KB). Im CMakeLists.txt: -DLODEPNG_NO_COMPILE_ALLOCATORS (PNG-Dekodierung im PSRAM).

Notfall-App (`recovery/`)

Ein eigenes, reines ESP-IDF-Projekt (kein Arduino): Display, Touch und der LVGL-Port kommen aus src/ (mit recovery/shim/Arduino.h für delay() und millis(); die Hauptfirmware hat dafür src/platform/Arduino.h), die Oberfläche ist in recovery/main/ui.cpp in Code gebaut. Sie läuft aus der Partition factory (1,5 MB, die App hat etwa 0,6 MB) und nutzt dieselbe Partitionstabelle (../partitions.csv).

Entwicklungswerkzeuge: bash build.sh recovery -DNOTFALL_SNAPSHOT=1 gibt jeden Bildschirm halb skaliert als Text auf der seriellen Schnittstelle aus (python3 tools/notfall_snap.py PORT /tmp/nf 60 --reset macht PNGs daraus) und nimmt Tasten per Zeichen entgegen (1 Firmware, 2 Komplett, 3 Nur Reset, 4 Normal, k/a/b Quelle, j/n Ja/Nein, z Zurück); mit -DNOTFALL_DEMO=1 zeigt sie zusätzlich alle Bildschirme mit Beispieldaten. Das Rollback lässt sich mit TESTHANG=1 TESTVERSION=9.9.9-test bash build.sh prüfen (baut eine absichtlich hängende Firmware; danach bash build.sh ohne die Variablen).

Reines ESP-IDF (seit v0.6.0)

Arduino-ESP32 ist entfernt. Die Anwendung nutzt weiter die vertrauten Namen, die src/platform/ auf ESP-IDF abbildet (WiFi.h + wlan.cpp, HTTPClient, WebServer, DnsPortal, Preferences.h, fusion_string.h mit eigener String-Klasse, Arduino.h mit millis(), delay(), ESP.getFreeHeap() …, Zeit.cpp für SNTP):

Früher (Arduino)	Jetzt (ESP-IDF)
`WiFi`, `WiFiClientSecure`, `HTTPClient`	`esp_wifi` (auf dem P4 über `esp_wifi_remote`), `esp_http_client` mit Zertifikatspaket
`WebServer`, `DNSServer`	`esp_http_server`, eigener DNS-Responder für das Captive Portal
`Preferences`	`nvs_flash`
`ESPmDNS`	Komponente `mdns`
`Update`	`esp_https_ota`
`String`, `Serial`	`std::string`, `ESP_LOG`
`ArduinoJson`	bleibt (reine C++-Bibliothek)

Speicher (ESP32-S3)

Speicher	Verwendung
Interner RAM (ca. 320 KB nutzbar)	Variablen, Heap (WLAN, LWIP), Stacks, LVGL-Zeichenpuffer (20 Zeilen), RGB-Bounce-Buffer, 64-KB-Cache; nach dem Start ca. 65 KB frei
PSRAM (8 MB)	Framebuffer (1,2 MB), Programmcode, LVGL-Speicherpool (192 KB), TLS-Puffer, Kartenbild, große Downloads (nach dem Start ca. 3 MB frei)
Flash (16 MB)	Programm, Bilder, Schriften, Einstellungen (NVS)

Die Warnkarte braucht beim Dekodieren ca. 3 MB am Stück im PSRAM; die alte Karte wird deshalb vorher freigegeben.

Oberfläche mit PicoPixel

In PicoPixel nach src/ui/ exportieren.
./tools/deploy_ui.sh ausführen: setzt die Wetter-Icons aus assets/icons/weather/ ein (Meteocons, auch wenn PicoPixel noch die alten Bilder enthält), benennt die Bilddateien in .inc um, passt images.c an, schaltet die Screen-Überblendung ab (Absturz-Fix), korrigiert Farb-Präfix und Sonderzeichen und prüft, ob alle vom Code verdrahteten Objekte noch existieren.
Die Schriften enthalten nur ASCII und ° Ä Ö Ü ß ä ö ü; andere Zeichen ersetzt bereinigeText().
Icons aus dem Code: PicoPixel begrenzt die Bilder. python3 tools/icons_code.py wandelt PNGs aus assets/icons/ in LVGL-Bilder um (assets/icons/code/, Tabelle src/icons/icons.cpp); iconSetzen(obj, "name", px) setzt Quelle und Zoom aus der Zielgröße. Die Icons der Allergen-/Biowetter-Screens stehen in PicoPixel nur als Platzhalter, deploy_ui.sh ersetzt sie durch 1×1-Bilder (spart Flash) und die Firmware setzt die echten Icons. Neue Icons: PNG ablegen, in tools/icons_code.py eintragen, Skript ausführen.

Releases und Update-Weg

Die Firmware-Dateien in docs/firmware/ und die Releases erstellt der Maintainer aus einem Build (Bootloader, Partitionstabelle, boot_app0.bin und Firmware stammen aus demselben Stand). Pull Requests bitte ohne Änderungen an docs/firmware/.

Die Geräte holen version.json über raw.githubusercontent.com und die Firmware von GitHub Pages. Ein Gerät bietet nur höhere Versionen an.

Mitmachen, Lizenz und Credits

Der Quellcode steht unter der Apache-Lizenz 2.0 (LICENSE, NOTICE), Texte und Bilder unter CC BY-NC 4.0. Name und Logos von „WetterCube“ sind nicht freigegeben. Pull Requests und Issues sind willkommen; Beiträge werden unter der Apache-Lizenz 2.0 aufgenommen. Hinweis: src/ui/ ist ein PicoPixel-Export; kleine Änderungen an der Oberfläche besser im Code (src/app/ui_*.cpp) machen. Die kostenlose Wetter-Schnittstelle von Open-Meteo ist nur für nicht-kommerzielle Nutzung gedacht.

Wetter- und Sensor-Icons von Meteocons (Bas Milius, MIT), Bedienelemente-Icons aus den Flat Color Icons von Icons8 (MIT / Good Boy License), Schrift Montserrat (SIL OFL 1.1), siehe CREDITS.md. Drittanbieter-Ressourcen behalten ihre Lizenzen.