# 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 until `hardware_uart: UART0` was 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_key` in `secrets.yaml` is 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-7` page, 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 `ch422g` component (`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:
1. **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.
2. **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.
3. **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
- [x] 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