WetterCubePlus/Entwicklung/en

Dies ist die englische Fassung. Zur deutschen Fassung

Repository layout

File / folder	Content
`WetterCubePlus.ino`	main program (Wi-Fi, data fetching, UI filling, web interface, calculator, game)
`webui_html.h`	HTML of the web interface and the setup portal
`build_opt.h`	compiler switches (`-Os`, `LV_COLOR_16_SWAP`, `LV_MEM_SIZE`, `LV_MEM_PSRAM`)
`lv_conf.h.example`	LVGL configuration (copy as `lv_conf.h` into the Arduino `libraries` folder)
`partitions.csv`	custom partition table (2× 4 MB app, rest SPIFFS)
`src/ui/`	PicoPixel export of the user interface (LVGL 8)
`WetterAmpel/`	firmware of the ESP32-C3 add-on
`docs/`	GitHub Pages: web installer, `version.json`, `manifest.json`, `firmware/*.bin`
`screenshots/`	photos for the README and this wiki
`bump_version.sh`, `deploy_ui.sh`	helper scripts (see below)
`CHANGELOG.md` / `CHANGELOG.en.md`, `DEVLOG.md`	changes (bilingual) and development diary

Building

Arduino IDE: board ESP32S3 Dev Module, PSRAM OPI PSRAM, Flash Size 16 MB, Partition Scheme Custom. Libraries: LovyanGFX (≥ 1.2), LVGL 8.3.x, ArduinoJson. Also provide lv_conf.h (see the section "Manual Installation" in the README).

Command line:

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

Without these options the compiler wrongly reports "sketch too big", because the default partition table applies.

Cache trap: After every change to build_opt.h, clear the Arduino sketch cache (~/Library/Caches/arduino/sketches/…) and restart the IDE, otherwise the new switches are not applied. Duplicate files: If the Arduino library folder lives in iCloud, conflict copies such as file 3.c sometimes appear. They cause "multiple definition" link errors and must be deleted.

Memory

Memory	Use
Internal RAM (about 320 KB usable)	variables, heap (Wi-Fi; HTTPS/TLS needs about 40–50 KB), stacks
PSRAM (8 MB, slower)	LVGL memory (`-DLV_MEM_PSRAM`), draw buffers, radar image, game board, large downloads
Flash (16 MB)	program, icons, fonts, settings (NVS)

Since v1.3.0 the LVGL memory lives in PSRAM. That gave the internal heap about 130 KB back (lowest heap level from 25 KB to about 157 KB). With LV_MEM_PSRAM, lv_mem_monitor() returns no values, so the sketch uses the free PSRAM instead.

Partitions (16 MB flash):

Partition	Size	Purpose
`nvs`	20 KB	settings (Wi-Fi, brightness, high scores …), kept across updates
`otadata`	8 KB	remembers the active app slot
`app0`, `app1`	4 MB each	two firmware slots: an update is written to the other one, then the device switches
`spiffs`	about 8 MB	reserved, not used in the code

The firmware currently takes about 2.8 MB; about 1.4 MB remain free in the 4 MB slot. Icons are therefore created at 128×128 (a 256 icon costs 196 KB, a 128 one 49 KB). The partition table cannot be changed by an update, only via USB or the web installer.

User interface with PicoPixel

Export from PicoPixel to src/ui/.
Run ./deploy_ui.sh. The script adapts the export (LVGL include, image files .c → .inc, 0xff color fix, FADE_IN → NONE to avoid a crash, special character ²) and checks that all objects used by the sketch still exist.
Check after every export: PicoPixel occasionally renumbers button names; the wiring (REG_CB) in the sketch must match the names.
Icons: upload new images at 128×128 and create them at 83×83; PicoPixel computes the zoom from widget and image size itself. Icons set at runtime need their own zoom (setWetterIcon() in the sketch).

Release process

bash bump_version.sh X.Y.Z sets the version everywhere (firmware, version.json, manifest.json, web page, README badges).
Update CHANGELOG.md and CHANGELOG.en.md, plus DEVLOG.md.
In the Arduino IDE use Sketch → Export Compiled Binary; firmware.bin must end up in docs/firmware/.
bash bump_version.sh --check verifies that everything is consistent and the binary contains the version.
Before committing, check the diff for credentials (the repo is public), then commit, push, create the tag vX.Y.Z and a GitHub release with the four files bootloader.bin, boot_app0.bin, partitions.bin, firmware.bin.

Devices fetch version.json via raw.githubusercontent.com and the firmware from GitHub Pages (docs/firmware/firmware.bin). A device only offers higher version numbers.

License and credits

The source code is licensed under the Apache License 2.0 (see LICENSE and NOTICE; versions up to v2.1.2 are under CC BY-NC 4.0), texts, images and the 3D-print files under CC BY-NC 4.0 (LICENSE-Dokumentation.txt); the weather icons are from Meteocons (MIT, since version 1.6.5; formerly Dovora), the font is Montserrat (SIL OFL 1.1), the UI control icons (home, gear, arrows, plus, calculator, game) from Icons8 Flat Color Icons (MIT or Good Boy License); details in CREDITS.md.