7.9 KiB
Phase 1 Build Notes
Status (2026-07-11)
Firmware flashed and running on physical hardware. Boot log confirms:
- I2C bus scan found all 3 expected devices:
0x24(CH422G),0x5D(GT911),0x76(BME280) - Display shows "Thermostat — Phase 1 OK" as expected
- GT911 touch attached with hardware interrupt (touch confirmed responsive via Waveshare's factory demo firmware; not yet confirmed under our own firmware/HA)
- BME280 sensor entities registered, no I2C errors
- WiFi connects cleanly, device reachable at
firecrest.local - Climate entity built with heat/cool modes and home/away presets, zero boot errors
- Fixed one real bug found during bring-up: ESPHome defaults ESP32-S3 logger to
USB_SERIAL_JTAG, a different physical USB port than this board's UART-flashing port — logs were silently going nowhere untilhardware_uart: UART0was set explicitly
Deferred / not yet verified (blocked on physical access to hardware):
- Relay bench test with multimeter — user doesn't have relays on hand, will test at office on a breadboard. GPIO wiring assumed correct for now based on clean compile + boot; not electrically verified.
- Full Home Assistant pairing —
ha_api_keyinsecrets.yamlis currently a placeholder (valid format, not a real key). Touch, sensor, switch, and climate entities not yet confirmed visible/controllable in HA itself.
Proceeding to Phase 2 (LVGL interface design, see circuitforge-plans/firecrest/superpowers/plans/2026-07-11-phase2-lvgl-ui.md) with the above two items still open — revisit before calling Phase 1 fully signed off. Phase 2's own implementation is now complete (all 5 tasks reviewed clean, ready to merge) but not yet flashed/verified on hardware — that verification and the two deferred items above are the same outstanding hardware-access gate.
Source: Waveshare Wiki, fetched 2026-07-11.
- https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-7B (confirmed this is the "Type B" product page — distinct from the non-B
ESP32-S3-Touch-LCD-7page, same pinout on both as of this writing) - Schematic PDF: https://files.waveshare.com/wiki/ESP32-S3-Touch-LCD-7/ESP32-S3-Touch-LCD-7-Sch.pdf
- GT911 datasheet: https://files.waveshare.com/wiki/common/GT911_EN_Datasheet.pdf
- No dedicated GitHub example repo — Waveshare ships Arduino/ESP-IDF demos as a wiki zip download, not a git repo. GT911 driver reference: https://github.com/espressif/esp-bsp/tree/master/components/lcd_touch/esp_lcd_touch_gt911
Waveshare ESP32-S3-Touch-LCD-7B — Confirmed Pin Assignments
LCD driver chip: ST7701. Touch chip: GT911. IO expander: CH422G (I2C address 0x24).
RGB Display Panel
Data width is 16-bit RGB565, but not wired as R0–R4/G0–G5/B0–B4 (the plan's placeholder assumption was wrong) — only the upper bits of each color channel are wired (R3–R7, G2–G7, B3–B7). This is a common cost-reduction technique since the low bits barely affect perceived color.
| Signal | GPIO |
|---|---|
| PCLK | GPIO7 |
| HSYNC | GPIO46 |
| VSYNC | GPIO3 |
| DE | GPIO5 |
| R3 | GPIO1 |
| R4 | GPIO2 |
| R5 | GPIO42 |
| R6 | GPIO41 |
| R7 | GPIO40 |
| G2 | GPIO39 |
| G3 | GPIO0 |
| G4 | GPIO45 |
| G5 | GPIO48 |
| G6 | GPIO47 |
| G7 | GPIO21 |
| B3 | GPIO14 |
| B4 | GPIO38 |
| B5 | GPIO18 |
| B6 | GPIO17 |
| B7 | GPIO10 |
Backlight and VCOM are NOT plain GPIO — they're behind the CH422G I2C IO expander:
| Signal | CH422G pin |
|---|---|
| DISP (backlight enable) | EXIO2 |
| LCD_VDD_EN (VCOM enable — must be driven high or the panel won't display correctly) | EXIO6 |
Touch (GT911 I2C)
| Signal | GPIO / Expander pin |
|---|---|
| SDA | GPIO8 (shared I2C bus) |
| SCL | GPIO9 (shared I2C bus) |
| INT (TP_IRQ) | GPIO4 |
| RST (TP_RST) | CH422G EXIO1 (not a raw GPIO) |
| I2C addr | 0x5D |
CH422G IO Expander
- I2C address:
0x24(fixed, not configurable) - Shares the same I2C bus as touch (GPIO8 SDA / GPIO9 SCL)
- Known pin assignments: EXIO1 = TP_RST, EXIO2 = DISP (backlight), EXIO4 = SD_CS, EXIO5 = USB_SEL/CAN_SEL, EXIO6 = LCD_VDD_EN
- Free expander pins: EXIO0, EXIO3, EXIO7 (3 pins) — only usable as low-current logic outputs, NOT suitable for driving relay coils directly (still need an external relay driver board either way)
- ESPHome has a native
ch422gcomponent (esphome/components/ch422g) — confirmed present in the esphome dev branch. Pin numbers 0–7 = EXIO0–EXIO7, plus 8–11 for other internal signals.
I2C Bus Map (single shared bus, GPIO8 SDA / GPIO9 SCL)
| Device | Address |
|---|---|
| CH422G IO expander | 0x24 |
| GT911 touch | 0x5D |
| BME280 (planned) | 0x76 (default) or 0x77 |
No address conflicts. BME280 should join this same I2C bus — there is a labeled "Sensor terminal" on the board broken out from this same bus, so no extra GPIO is consumed for the ambient sensor.
GPIO Budget — ⚠️ Flag for Phase 1 decision
This board commits nearly every exposed GPIO to an onboard peripheral:
| Peripheral | GPIO used |
|---|---|
| LCD RGB panel | 0,1,2,3,5,7,10,14,17,18,21,38,39,40,41,42,45,46,47,48 (20 pins) |
| Touch IRQ + shared I2C | 4, 8, 9 |
| TF/SD card (SPI) | 11 (MOSI), 12 (SCK), 13 (MISO) |
| RS485 | 15 (TXD), 16 (RXD) |
| USB / CAN (shared pins) | 19, 20 |
That accounts for 27 of the ESP32-S3's usable GPIOs. GPIO26–32 and 35–37 are reserved internally for octal PSRAM on this N16R8 module and aren't broken out. GPIO43/44 are UART0 TX/RX (used for USB-serial flashing/logging — avoid repurposing). There is no bank of 5 free general-purpose GPIO pins left on this board for the 5 relay outputs as the plan assumed.
Options to get 5 relay-driving outputs, in order of how much they cost you:
- Repurpose the RS485 pins (GPIO15, 16) and CAN/USB pins (GPIO19, 20) — 4 pins, if you don't need RS485/CAN on this build. Still short 1 pin.
- Also repurpose the TF card SPI pins (GPIO11, 12, 13) if the thermostat doesn't need an SD card — gets you to 7 free pins, plenty for 5 relays plus headroom.
- Add an external I2C GPIO expander (e.g., PCF8574) on the shared I2C bus (GPIO8/9) instead of touching onboard peripheral pins — keeps RS485/CAN/TF card available for future use, at the cost of one more part.
Decision (2026-07-11): Phase 1 proof-of-concept repurposes the TF/SD card SPI pins (GPIO11, 12, 13) and the RS485 pins (GPIO15, 16) for the 5 relay outputs. This is a stopgap — CAN/native-USB (GPIO19, 20) are left untouched for possible future use. SD card and RS485 are unavailable on this build. A future phase should replace this with an external I2C GPIO expander (e.g. PCF8574) on the shared bus, or a second ESP acting as an I2C/relay satellite, to restore SD card logging without sacrificing GPIO. (Note: "Phase 2" elsewhere in this repo now refers to the LVGL touchscreen UI work — this relay/SD-card item is tracked as a Phase 3+ TODO to avoid confusion, see circuitforge-plans/firecrest/superpowers/plans/2026-07-11-phase2-lvgl-ui.md Notes for Phase 3.)
Relay Outputs
| Relay | HVAC Terminal | GPIO | Repurposed from |
|---|---|---|---|
| 1 | G (fan) | GPIO11 | TF card MOSI |
| 2 | Y1 (cool 1) | GPIO12 | TF card SCK |
| 3 | Y2 (cool 2) | GPIO13 | TF card MISO |
| 4 | W1 (heat 1) | GPIO15 | RS485 TXD |
| 5 | W2 (heat 2) | GPIO16 | RS485 RXD |
Open Questions
- Relay GPIO source — resolved above (TF + RS485 pins for Phase 1; I2C expander or second ESP planned for a future phase to restore SD card)
- Confirm exact RGB timing porch/pulse values against schematic or ST7701 init sequence — plan's placeholder timing values are typical-for-1024x600 but unverified against this specific panel
- Confirm backlight PWM dimming path (tracked in Phase 2 plan's Notes for Phase 3) — currently backlight is on/off only via CH422G EXIO2, no PWM signal identified for brightness control