mattandClaude
d4b2ab7f99
Keep the HTTP session alive between weather polls (TODO #1). Re-creating the client each time forced a fresh TLS handshake inside the window where the UI is frozen. Measured on hardware: the fetch went from ~1.3s to ~80ms, so the pause is no longer long enough to matter once thermostat controls exist. The timeout drops from 30s to 10s once a session is warm, since only a cold handshake needs the longer budget. Any transport error or non-200 tears the session down so a half-open connection cannot poison every later poll. The response buffer is now reset per request rather than on HTTP_EVENT_ON_CONNECTED -- a kept-alive connection does not re-fire that event, so the buffer would have accumulated across polls. Indicate stale readings (TODO #2). After two consecutive failures the temperature dims and the status line shows the age. Age comes from tick counts, not weather_data_t.last_update: there is no SNTP client here, so time(NULL) starts at the epoch and any age derived from it is meaningless. Gate the touch readout behind UI_DEBUG_TOUCH, default off (TODO #3). Kept the note about LVGL not bubbling events to parents -- it documents a real trap. Delete main/utils (TODO #4); it had no callers outside itself. Also refreshed project_structure.txt, which was additionally missing i2c_bus and backlight. Lay out two 4MB OTA slots (TODO #5) while no devices are fielded, and document in the README that an OTA download cannot run while the panel is scanning -- the flash write faults the bounce-buffer ISR. Log the truncation warning once per response instead of once per chunk, and record the weather task's stack high-water mark (TODO #6): ~2400 bytes spare of 6144. Co-Authored-By: Claude <noreply@anthropic.com>
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.
Currently displays outdoor conditions from an Ambient Weather personal weather station. 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/wifi |
WiFi station bring-up |
main/api |
Ambient Weather REST client |
Setup
cp main/app_config.h.example main/app_config.h
# edit main/app_config.h: WiFi credentials + Ambient Weather keys
main/app_config.h is gitignored — it holds your WiFi password and API keys.
Build & Flash
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).
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.
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 16-scanline bounce buffer stages each chunk in internal RAM. 20 scanlines would be better but needs 64KB of internal RAM and fails to allocate once WiFi is up.
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.
Gotchas
- 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. The touch readout polls the input device from an
lv_timerinstead. 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 throughlabel_set_if_changed().- WiFi must be brought up before
display_init(). The bounce refill ISR reads PSRAM, which shares the cache with flash; an NVS write while the panel is running faults it with "Cache disabled but cached memory region accessed".
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_init() and CONFIG_ESP_WIFI_NVS_ENABLED is off to keep the
WiFi stack from writing later.