# Thermostat HMI ESP-IDF firmware for the **Elecrow CrowPanel 7" Advance** (ESP32-S3-WROOM-1-N16R8, 16MB flash + 8MB octal PSRAM, 800×480 IPS, GT911 capacitive touch). > **Board variant matters.** Elecrow sells a *Basic* CrowPanel 7" and an > *Advance* CrowPanel 7". They share a form factor and almost nothing else: > every RGB data pin, every sync pin, the pixel clock, the porches, the sync > polarities and the touch I2C pins are different, and the Advance drives its > backlight over I2C instead of from a GPIO. This firmware targets the > **Advance**. Building it against Basic documentation yields a black screen > and a silent I2C bus. A wall dashboard driven by **Home Assistant** over the LAN: outdoor and indoor conditions from an Ambient Weather station, sunrise/sunset, rain, a five-day forecast, and on/off plus brightness control for six lights. Thermostat control (setpoint, HVAC relays, scheduling) is not implemented yet. ## Components | Path | Purpose | |------|---------| | `main/drivers/display` | RGB parallel panel via `esp_lcd`, double-buffered in PSRAM | | `main/drivers/touch` | GT911 capacitive touch over I2C, registered as an LVGL input device | | `main/ui/lvgl_port.c` | LVGL tick source, service task, and locking | | `main/ui/ui_manager.c` | Screen layout and update entry points | | `main/ui/icon_font.c` | Generated ~6KB MDI icon subset — see `tools/make_icon_font.py` | | `main/wifi` | WiFi station bring-up | | `main/api/ha_client.c` | Home Assistant REST transport (device only) | | `main/api/ha_data.c` | Response parsing and presentation helpers (**shared with the simulator**) | | `main/api/ha_config.h` | Entity IDs for this installation | | `main/api/ambient_weather.c` | Ambient Weather cloud client — **fallback only** | | `sim/` | Desktop simulator for the UI — see `sim/README.md` | | `tools/` | `ha_discover.py`, `ha_snapshot.py` | ## Setup ```bash cp main/app_config.h.example main/app_config.h # edit main/app_config.h: WiFi credentials + HA_TOKEN ``` `main/app_config.h` is gitignored — it holds your WiFi password and the Home Assistant token. Entity IDs are *not* secrets and live in `main/api/ha_config.h`, which is tracked. Confirm the entity IDs still resolve after any change in HA: ```bash export HA_TOKEN='...' # HA: your user -> Security -> Long-lived tokens python3 tools/ha_discover.py ``` A wrong entity ID fails **silently** as "unavailable" rather than as an error. ## Build & Flash ```bash idf.py set-target esp32s3 idf.py build flash monitor ``` Requires ESP-IDF **v5.3 or newer** (the code uses the `i2c_master` driver API and `dma_burst_size`). ## Thermostat control Single-stage gas furnace, no A/C. The control loop is in `main/control/thermostat.c` and is **pure logic** — no ESP-IDF, no network, no clock of its own. The caller supplies a temperature and a millisecond timestamp; that is what lets the desktop simulator and the test harness run the identical decision code. | Protection | Value | Why | |---|---|---| | Deadband | 1.0 °F | stops the burner chattering at the setpoint | | Minimum on | 3 min | a shorter call delivers almost no heat for a full ignition's wear | | Minimum off | 5 min | back-to-back ignitions are what kill igniters | | Cycles/hour | 5 | standard gas default; catches a flapping sensor | | Boot lockout | 60 s | a boot loop must not machine-gun the gas valve | | Sensor staleness | 15 min | see below | Verify after any change to that file — it switches a gas valve: ```bash gcc -Wall -Wextra -I main/control -o /tmp/therm_test \ tools/thermostat_test.c main/control/thermostat.c -lm && /tmp/therm_test ``` Two decisions worth knowing: - **G is never energized during a heat call.** The furnace runs its own blower with a fan-on delay that waits for the heat exchanger and a fan-off delay that scavenges residual heat. Driving G ourselves would blow cold air at people and throw that heat away. G is manual circulation only. - **The control loop starts before any of app_main's early returns.** Every one of those is about WiFi or HA being unusable, and none of them is a reason to leave a house unheated. ### The sensor is the weak link Indoor temperature arrives over the network from Home Assistant. If HA stops answering, the reading ages; after 15 minutes the state becomes `NO_SENSOR`, heat is forced off and the card turns red. Running blind on an old number could overheat the house or let it freeze, and neither is acceptable. This is a deliberate compromise, not a design. **The real fix is a local sensor on the I2C bus**, which removes the failure mode entirely — an SHT30 or BME280 at a free address. Note the panel dissipates ~5 W, so it must be remote from the enclosure or it will read several degrees high. **Setpoint does not survive a reboot** (defaults to 68 °F). Persisting it would mean an NVS write, and a flash write while the panel is scanning faults the bounce-buffer ISR — see Memory notes. Storing it in an HA `input_number` would work and needs no flash. ## Home Assistant Everything on screen except the forecast comes from **one** POST to `/api/template`: about 430 bytes, measured at ~85 ms on the LAN. The Jinja template lives in `main/api/ha_template.h` and is built by the preprocessor from the same `HA_LIGHT_LIST` X-macro as the C table, so the request and the code that reads the reply cannot drift apart. Three things fall out of doing it this way, and all three are load-bearing: - **No SNTP, and no timezone database.** HA renders `sunrise`, `sunset`, `clock` and `date` as local-time strings. The board's own clock still starts at the epoch and it no longer matters — but note that means *nothing on this device knows the time*, so anything needing a real clock (scheduling, say) has to solve that separately. There is an unused RTC at I2C 0x51. - **No TLS.** Plain HTTP to a box on the same switch. The cloud client pays a multi-second handshake; this does not, which matters because the caller pauses rendering for the duration. Pointing `HA_HOST` at an https:// instance throws that away. - **Unavailable sensors arrive as JSON `null`,** never a sentinel number. `-1` mph of wind is impossible, but `-1` °F of dew point is not. The forecast is a second, slower request (every 30th poll). It cannot be part of the template: HA removed the `forecast` attribute from weather entities in 2024.4, and templates cannot call services. ### The wind sensors are dead The station's anemometer has been offline since **2026-07-27**: `wind_speed`, `wind_gust`, `wind_direction` and `feels_like` all read `unavailable`, and the WIND tile shows `--` by design. It is deliberately *not* backfilled from the met.no forecast — regional modelled wind under a heading that means "my yard" is worse than showing nothing. `sensor.moonlight_beach_max_gust` is a trap: it is **not** unavailable. It still reports its last value from 2026-07-28 and will render as a plausible live number. Anything that uses it needs a staleness check first. ### Fallback When HA cannot be reached, `ambient_weather.c` fills in outdoor temperature, humidity and wind from the cloud API and the status line says so. Indoor, sun, forecast and lights have no cloud equivalent and hold their last values. ## Hardware (Advance) ### RGB panel (16-bit RGB565) | Signal | GPIO | |--------|------| | DE | 42 | | VSYNC | 41 | | HSYNC | 40 | | PCLK | 39 | | R0–R4 | 7, 17, 18, 3, 46 | | G0–G5 | 9, 10, 11, 12, 13, 14 | | B0–B4 | 21, 47, 48, 45, 38 | Timings: 18 MHz pixel clock, HFP 8 / HPW 4 / HBP 8, VFP 8 / VPW 4 / VBP 8. Both syncs idle high; PCLK is `pclk_active_neg`. ### I2C bus — GPIO 15 (SDA) / 16 (SCL) | Address | Device | |---------|--------| | 0x30 | STC8H1K28 board controller — backlight **and GT911 reset** | | 0x51 | RTC | | 0x5D | GT911 touch | The GT911 has **no ESP32 reset or interrupt GPIO** on this board. The STC8H1K28 holds it in reset, so `backlight_init()` must run before `touch_init()` or the touch controller NACKs every address. STC8H1K28 protocol is single raw bytes, no register addressing: `0x19` wake, then `0x10` and `0x18` to configure and release the GT911. Brightness is `0x00`–`0xF5` **inverted** (`0x00` = full) on v1.3; v1.2 uses a narrower `0x05`–`0x10` range instead. ### UART1-OUT plug — the only free GPIO on this board Nearly every pin is spoken for: 20 on the RGB bus, 2 on I2C, IO4/5/6 on I2S+SD, IO8 buzzer, IO43/44 the console. The UART1-OUT plug (PH2.0-4P) is what's left, and it is where the furnace relays connect. | Wire | Pin | | |------|-----|---| | black | GND | | | red | 3.3 V | 1 A budget; two relay coils ≈ 260 mA | | white | **IO20** | measured, not documented by Elecrow | | yellow | **IO19** | measured, not documented by Elecrow | Elecrow publishes the GPIO numbers but **not the pin order**, so the white/yellow mapping above was measured on this board (2026-08-05) by driving each pin at a distinct blink rate and metering the plug. Static levels cannot work for this: a pin held high is indistinguishable from the 3.3 V rail, and one held low from GND. Both pins were also confirmed electrically free — each follows an internal pulldown to 0 and pullup to 1, so nothing else is driving them. > **IO19/IO20 are shared** with the onboard I2S mic (MIC_CLK/MIC_SD) and are > the ESP32-S3's native USB D−/D+. DIP switches select the mic away: > S1=0 S0=1 is *wireless module* mode, which leaves these pins to us. Native > USB is unused — the board flashes over UART0 through a CH340 > (`/dev/ttyUSB0`), so `CONFIG_USJ_ENABLE_USB_SERIAL_JTAG` and > `CONFIG_ESP_PHY_ENABLE_USB` can both be turned off to release the pins > fully. ## Display architecture Two 800×480×2 framebuffers in PSRAM, LVGL in `RENDER_MODE_DIRECT`. LVGL draws into whichever buffer the LCD is *not* scanning; the last flush of a refresh hands that buffer to the panel, which switches to it. Nothing ever writes into the buffer being displayed — copying into the live framebuffer races the LCD's own reads, and the resulting corrupt pixels persist indefinitely because LVGL does not know they are wrong and never reinvalidates them. A **20**-scanline bounce buffer stages each chunk in internal RAM (64KB across two buffers). This was 16 for a long time because 20 "fails to allocate once WiFi is up" — which was true when `display_init()` ran after `wifi_init_sta()`. The two-phase split changed that: `display_alloc()` now takes these buffers from a virgin heap with ~200KB free, long before WiFi has fragmented it. Bigger chunks give the refill ISR more time to fetch the next one before the LCD needs it, which attacks the artefact mechanism directly. That leaves ~24KB of internal heap once everything is up. Watch the "Free internal heap" log line — if it approaches single digits, come back down to 18 or 16 scanlines. ### Known limitation: occasional left-edge artefacts Short stale lines sometimes appear at the left edge, most often right after a weather fetch. The panel needs ~34 MB/s sustained from PSRAM at the 18MHz pixel clock, and 80MHz octal PSRAM is marginal for that. When the bounce refill ISR runs late — WiFi interrupt activity is enough — the panel scans out whatever was left in the buffer. The pixel clock is not a usable lever: below roughly 40Hz refresh (about 15MHz) the panel stops locking and the image rolls vertically instead. The real fix is 120MHz PSRAM, which is what the vendor's Arduino build uses (`-DCONFIG_SPIRAM_SPEED_120M=1`). On ESP-IDF 5.3 that is not safely reachable: selecting it raises the shared MSPI core clock, and IDF only ships flash timing tables pairing 120MHz PSRAM with 120MHz flash. Flash above 80MHz requires High Performance Mode and a DC-aware bootloader. ## UI development `main/ui/ui_manager.c` and `main/api/ha_data.c` are compiled **unmodified** into a desktop simulator, so layout work does not need a flash cycle: ```bash cmake -S sim -B sim/build -G Ninja && cmake --build sim/build ./sim/build/thermostat_sim # SDL window, mouse = touch ./sim/build/thermostat_sim --png /tmp/shot.png # headless capture ``` Capture real states to iterate against, instead of waiting for reality: ```bash export HA_TOKEN=$(cat ~/.config/thermostat-hw/ha_token) python3 tools/ha_snapshot.py --name rainy ./sim/build/thermostat_sim --data sim/snapshots/rainy.json \ --forecast sim/snapshots/rainy.forecast.json ``` See `sim/README.md` for what it does and does not reproduce. It says nothing about PSRAM bandwidth or panel timing. > **The font lists in `sim/lv_conf.h` and `sdkconfig.defaults` must match.** > A size enabled in one build and not the other makes the simulator lie about > layout. Worse, `sdkconfig.defaults` only seeds a *new* `sdkconfig` — editing > it does nothing to an existing one, so change `sdkconfig` too (or delete it > and let it regenerate). ## Gotchas - **Setting a style property always invalidates, even to an identical value.** `lv_obj_set_local_style_prop()` calls `lv_obj_refresh_style()` unconditionally — there is no equality short-circuit, unlike the one you might assume by analogy with `label_set_if_changed()`. A periodic update that restyles widgets "harmlessly" is a periodic full repaint of them. This cost a round of debugging: `ui_update_thermostat()` ran at 1Hz writing seven styles, which turned the left-edge artefacts from occasional into permanent. Every update path here is now change-guarded. - **Do not repaint to fix artefacts.** It is tempting, because LVGL never reinvalidates pixels it does not know are wrong. But the corruption scales with how much is written, so a full-screen invalidate is 768KB of exactly the PSRAM contention that causes it. Two attempts at this (post-poll and a post-interaction "repair" timer) both made it visibly worse and were removed. Redraw *less*, not more. - **LVGL does not bubble events to parents.** An event handler on the screen object never sees taps that land on a child widget, which looks exactly like dead touch zones. Light tiles therefore carry their own handlers, and the labels inside them are left non-clickable so taps reach the tile. - **Montserrat has no `·` (U+00B7) or `—` (U+2014).** Both render as tofu boxes. `weather_get_string()` emits a middot, but only into a log line. Anything reaching a label must stay in Latin-1; the UI uses `--`. - **`LV_LABEL_LONG_DOT` needs an explicit height** to truncate. With a content-sized height the label wraps to a second line first and only then adds dots — landing on top of whatever is below it. - **Icons are label text**, not images: single glyphs from a subset MDI TTF rasterised by tiny_ttf (`tools/make_icon_font.py` regenerates `main/ui/icon_font.c` / `ui_icons.h`; needs network + fonttools, so the generated files are committed). Codepoints are resolved from the MDI CSS at generation time — never hardcode one, MDI reassigns them between majors. - **Light tiles are optimistic.** A tap flips the tile immediately and holds against poll data for up to 5s until HA confirms (`light_hold_t`); commands are sent on finger-lift only, and poll updates never touch a pressed slider. Breaking any of those three rules brings back the "button waits a second, then the knob jumps out from under your finger" feel. - **`lv_label_set_text()` invalidates unconditionally**, even when the text is identical — so setting an unchanged value still forces a repaint. All label updates go through `label_set_if_changed()`. - **Display bring-up is two-phase, and both orderings are load-bearing.** `display_alloc()` runs *before* WiFi: the bounce buffers need two contiguous 25.6KB internal DMA blocks, and WiFi's RX buffer churn fragments the heap within seconds — observed as a boot-loop with 84KB free and no block big enough. `display_start()` runs *after* WiFi: once scan-out begins, the bounce refill ISR reads PSRAM, which shares the cache with flash, and an NVS/PHY write would fault it with *"Cache disabled but cached memory region accessed"*. Allocate early, scan late. ## Partitions Two 4 MB OTA slots (`ota_0` / `ota_1`) with `otadata`, laid out in `partitions.csv`. The app is ~1.4 MB, so the slots are generous — but the layout is fixed once devices are fielded, and re-partitioning later means reflashing each one over USB. ~7.9 MB of the 16 MB is left unallocated; adding a partition to free space is safe, moving an existing one is not. > **OTA is not yet implemented, and it is not a drop-in.** Writing an OTA image > is a flash write, and the bounce-buffer refill ISR reads PSRAM, which shares > the cache with flash on the S3 (see Memory notes). Downloading an update > while the panel is scanning **will** fault that ISR. Any implementation must > stop the panel for the download and write, or reboot into a dedicated > updater mode first. ## Memory notes Two 800×480×2 framebuffers (750 KB each) live in PSRAM. The 8 MB **octal** PSRAM at 80 MHz is required — QSPI cannot sustain the RGB refresh. Do **not** enable `CONFIG_SPIRAM_FETCH_INSTRUCTIONS` / `CONFIG_SPIRAM_RODATA`: they contend with the panel for PSRAM bandwidth. The bounce buffer **is** enabled (the panel cannot stream straight from PSRAM), which is exactly why flash writes are dangerous while the panel runs: the refill ISR reads PSRAM, which shares the cache with flash on the S3, so an NVS write faults it with *"Cache disabled but cached memory region accessed"*. All flash writes happen before `display_start()` and `CONFIG_ESP_WIFI_NVS_ENABLED` is off to keep the WiFi stack from writing later. Static buffers beware: `.bss` lives in the same internal RAM the bounce buffers come from, with only ~33KB of slack after the panel is up — a few KB of new static array is enough to matter (the trend ring is deliberately time-bucketed down to ~720 bytes for this reason).