WetterCube/Entwicklung/en

Dies ist die englische Fassung. Zur deutschen Fassung

Repository layout

File / folder	Content
`wettercube.ino`	the whole application: setup, loop, touch button, portal, weather/pollen/air-quality requests, web interface, diagnostic log, OTA
`screens.c/h`, `images.c/h`, `colors.c/h`, `styles.c/h`, `fonts.c/h`, `ui.c/h`, `actions.`, `vars.`	PicoPixel export of the UI (LVGL 8.3, 240×240)
`font_montserrat_*.c`	the fonts generated by the export (kept in the sketch folder, see below)
`images/`	placeholders (1×1 px) for the former PicoPixel images, stays a subfolder
`wetter_icons.c/.h`, `icons/`	weather and warning icons (Meteocons) as LVGL images, generated by `tools/wetter_icons.py`
`assets/icons/`	PNG sources of the icons and the Meteocons license text
`tools/wetter_icons.py`	converts the PNGs into the firmware images (Python 3 with Pillow)
`build_opt.h`	project-local compiler switches
`partitions.csv`	custom partition table
`docs/`	GitHub Pages: web installer, `version.json`, `manifest.json`, `firmware/*.bin`
`CHANGELOG.md`, `DEVLOG.md`, `CREDITS.md`, `LICENSE`	changes, development diary (German), credits, MIT license

Building

Arduino IDE: ESP32 core 3.3.x, libraries LVGL 8.3.x, Arduino_GFX_Library, ArduinoJson 7.x. The shared lv_conf.h lives in Arduino/libraries/ next to the lvgl folder. Board ESP32C3 Dev Module with:

Menu	Value
USB CDC On Boot	Enabled
CPU Frequency	160 MHz
Flash Size / Mode / Frequency	4 MB / QIO / 80 MHz
Partition Scheme	Custom (the sketch's `partitions.csv`)
Upload Speed	921600

Command line:

arduino-cli compile --fqbn "esp32:esp32:esp32c3:UploadSpeed=921600,CDCOnBoot=cdc,CPUFreq=160,FlashFreq=80,FlashMode=qio,FlashSize=4M,PartitionScheme=custom,DebugLevel=none" .

Without the Custom partition scheme the compiler reports "sketch too big" because the default table offers less room.

`build_opt.h`

Switch	Effect
`-Os`	optimize for size
`-DLV_COLOR_16_SWAP=0`	Arduino_GFX swaps the bytes itself. With `1` the colors are wrong
`-DLV_MEM_SIZE=98304`	96 KB of LVGL memory. Less: icons are missing. More: not enough free heap for the TLS handshake (HTTPS)

The switches live in a project-local build_opt.h because the global lv_conf.h is shared by all Arduino projects. Compiler -D flags always win over lv_conf.h.

Memory and partitions

The ESP32-C3 has 4 MB of flash and no PSRAM. The HTTPS requests need about 40–50 KB of free heap, which is why LVGL is limited to 96 KB. HTTPS always goes through WiFiClientSecure with setInsecure() (no certificate check); an HTTPClient alone with an https:// URL returns HTTP -1 under core 3.3.x. getLocalTime() is called with a timeout of 0 so that it does not block for up to 5 seconds.

Partition	Size
`nvs`	20 KB (settings, kept across updates)
`otadata`	8 KB
`app0` / `app1`	2,031,616 bytes each (the update is written to the respective other slot)

The SPIFFS partition was removed (the cube only uses NVS), so the slots comfortably fit the ~1.8 MB firmware. The partition table cannot be changed by an update, only via USB or the web installer.

UI with PicoPixel

The UI is built in the browser-based LVGL editor PicoPixel (formerly SquareLine Studio, switched in v1.8.0).

Export from PicoPixel into the sketch folder.
Copy the fonts from the fonts/ subfolder into the sketch folder and change the include paths from fonts/fonts.h to fonts.h (e.g. in screens.c and styles.c). The images stay in the images/ subfolder (images.c includes images/*.c), then run python3 tools/wetter_icons.py (puts the placeholders back, see below).
Always recompile after the last export before committing. A late re-export overwrites the path fixes and breaks the build otherwise (this happened in v1.8.1 and was fixed in v1.8.2).
Elements are accessed through the central objects struct, e.g. objects.labeltemp.

Weather icons

The weather and warning icons do not come from PicoPixel but from tools/wetter_icons.py: the script crops the PNG sources (assets/icons/wetter/, 32 PNGs of which 28 are used, assets/icons/warn/) to their commonly occupied area, scales them (weather icons 48×48, warning icons 80×80) and writes LVGL images to icons/. The mapping of weather codes is in wmoZuImage() in wettercube.ino; the warning icons are set in setup().

The PicoPixel images in images/ (day_clear, rain, alert …) only remain as 1×1 placeholders because screens.c refers to those names. After every PicoPixel export run python3 tools/wetter_icons.py, because the export overwrites the placeholders with the big originals. Each icon (48×48) needs 6.9 KB of flash. They are displayed at 73 px (main screen) and 52 px (forecast): setWeatherIcon() zooms to the widget size set in PicoPixel, so the size can be changed there; bigger images quickly use more (256×256 px ≈ 196 KB).

Release process

Set FIRMWARE_VERSION in wettercube.ino, docs/version.json and docs/manifest.json to the new version.
Test locally. In the Arduino IDE choose Sketch → Export Compiled Binary.
Copy the four binaries (bootloader, partitions, boot_app0, firmware) to docs/firmware/ (the web installer needs all four, OTA only firmware.bin).
Update CHANGELOG.md and DEVLOG.md.
Commit, push and create a GitHub release. GitHub Pages needs a few minutes afterwards.

The cube fetches version.json and firmware/firmware.bin from https://jppeterson-lab.github.io/WetterCube/ (the capitalization of the repository name must match exactly).

License and credits

The source code is licensed under the MIT License. The weather icons are the Meteocons by Bas Milius (MIT), the case by Keralots. Details in CREDITS.md.