docs: add phase 1 hardware research notes and pin assignments

docs/build-guide-phase1-notes.md

@@ -0,0 +1,104 @@
+# Phase 1 Build Notes
+
+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.** Phase 2 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. Tracked as a Phase 2 TODO.
+
+### 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 Phase 2 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 (Phase 2) — currently backlight is on/off only via CH422G EXIO2, no PWM signal identified for brightness control