137 lines
5.4 KiB
Markdown
137 lines
5.4 KiB
Markdown
# 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 |
|
||
| `main/utils` | Small helpers |
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
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
|
||
|
||
```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`).
|
||
|
||
## 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_timer` instead.
|
||
- **`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()`.
|
||
- **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"*.
|
||
|
||
## 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. Do **not** enable the RGB
|
||
bounce buffer either — its refill ISR reads PSRAM, which shares the cache with
|
||
flash on the S3, so any NVS write faults it with *"Cache disabled but cached
|
||
memory region accessed"*.
|