121 lines
7.9 KiB
Markdown
121 lines
7.9 KiB
Markdown
# 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
|