From 5118eb8b1de58b79b734b39b639f3baede098b2c Mon Sep 17 00:00:00 2001 From: Gene Johnson Date: Sat, 14 Mar 2026 15:55:21 -0700 Subject: [PATCH 1/2] feat: Add a detailed hardware specification document for the Klubhaus Doorbell ESP32 development boards. --- klubhaus-doorbell-hardware.md | 136 ++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 klubhaus-doorbell-hardware.md diff --git a/klubhaus-doorbell-hardware.md b/klubhaus-doorbell-hardware.md new file mode 100644 index 0000000..77bb528 --- /dev/null +++ b/klubhaus-doorbell-hardware.md @@ -0,0 +1,136 @@ +# Klubhaus Doorbell — Hardware Spec Sheet + +Derived from source code analysis of [klubhaus-doorbell](https://git.notsosm.art/david/klubhaus-doorbell.git) and manufacturer datasheets. + +The project targets **three** ESP32-based development boards, each with an integrated TFT display and touch input. All three are all-in-one "ESP32 + screen" modules (not a bare Arduino with a separate breakout). + +--- + +## Board 1 — ESP32-32E (2.8″ ILI9341) + +| Attribute | Value | +|---|---| +| **Manufacturer** | Hosyond (likely) | +| **Module** | ESP32-32E (ESP32-WROOM-32 family) | +| **SoC** | ESP32-D0WD-V3, Xtensa dual-core 32-bit LX6 | +| **Max clock** | 240 MHz | +| **SRAM** | 520 KB | +| **ROM** | 448 KB | +| **Flash** | 4 MB (external QSPI) — per FQBN `FlashSize=4M` | +| **PSRAM** | Flagged in build (`-DBOARD_HAS_PSRAM`) — likely present but unconfirmed capacity | +| **WiFi** | 2.4 GHz 802.11 b/g/n | +| **Bluetooth** | v4.2 BR/EDR + BLE | +| **Display driver** | ILI9341 | +| **Display size** | ~2.8″ (inferred from `.crushmemory` note "original 2.8″ ILI9341") | +| **Resolution** | 320 × 240 (landscape rotation 1) | +| **Display interface** | 4-line SPI | +| **Color depth** | 65K (RGB565) | +| **Touch** | XPT2046 resistive (SPI) | +| **Backlight GPIO** | 22 | +| **SPI pins** | MOSI 23, SCLK 18, CS 5, DC 27, RST 33 | +| **Touch CS** | GPIO 14 | +| **SPI clock** | 40 MHz (display), 20 MHz (read), 2.5 MHz (touch) | +| **Serial baud** | 115200 | +| **USB** | Type-C (programming / power) | +| **Display library** | TFT_eSPI (vendored) | + +--- + +## Board 2 — ESP32-32E-4″ (Hosyond 4.0″ ST7796) + +| Attribute | Value | +|---|---| +| **Manufacturer** | Hosyond | +| **Module** | ESP32-32E | +| **SoC** | ESP32-D0WD-V3, Xtensa dual-core 32-bit LX6 | +| **Max clock** | 240 MHz | +| **SRAM** | 520 KB | +| **ROM** | 448 KB | +| **Flash** | 4 MB (external QSPI) — per FQBN `FlashSize=4M` | +| **PSRAM** | Flagged in build (`-DBOARD_HAS_PSRAM`) — likely present but unconfirmed capacity | +| **WiFi** | 2.4 GHz 802.11 b/g/n | +| **Bluetooth** | v4.2 BR/EDR + BLE | +| **Display driver** | ST7796S | +| **Display size** | 4.0″ | +| **Resolution** | 320 × 480 (landscape rotation 1) | +| **Display interface** | 4-line SPI | +| **Color depth** | 262K (RGB666) per manufacturer; firmware uses RGB565 | +| **Touch** | XPT2046 resistive (SPI) | +| **Backlight GPIO** | 27 (active HIGH) | +| **SPI pins** | MISO 12, MOSI 13, SCLK 14, CS 15, DC 2, RST tied to EN | +| **Touch CS / IRQ** | GPIO 33 / GPIO 36 | +| **SPI clock** | 40 MHz (display), 20 MHz (read), 2.5 MHz (touch) | +| **Serial baud** | 115200 | +| **Physical size** | 60.88 × 111.11 × 5.65 mm | +| **USB** | Type-C | +| **Display library** | TFT_eSPI (vendored) | +| **Reference** | [lcdwiki.com/4.0inch_ESP32-32E_Display](https://www.lcdwiki.com/4.0inch_ESP32-32E_Display) | + +--- + +## Board 3 — Waveshare ESP32-S3-Touch-LCD-4.3 + +| Attribute | Value | +|---|---| +| **Manufacturer** | Waveshare | +| **Module** | ESP32-S3-WROOM-1-N16R8 | +| **SoC** | ESP32-S3, Xtensa dual-core 32-bit LX7 | +| **Max clock** | 240 MHz | +| **SRAM** | 512 KB | +| **ROM** | 384 KB | +| **PSRAM** | 8 MB (onboard) | +| **Flash** | 16 MB — per FQBN `FlashSize=16M` | +| **WiFi** | 2.4 GHz 802.11 b/g/n | +| **Bluetooth** | v5.0 BLE | +| **Antenna** | Onboard PCB antenna | +| **Display driver** | RGB parallel (16-bit, 5-6-5 R/G/B channel split) | +| **Display size** | 4.3″ | +| **Resolution** | 800 × 480 | +| **Color depth** | 65K | +| **Touch** | GT911 capacitive, 5-point, I2C | +| **Touch I2C** | SDA 8, SCL 9, INT 4, addr 0x14 (runtime) / 0x5D (defined in config) | +| **I/O expander** | CH422G (I2C, shared bus with touch) — controls backlight, LCD reset, SD CS, etc. | +| **Pixel clock** | 14 MHz (LovyanGFX Bus_RGB) | +| **USB** | Type-C (UART via CH343P + native USB HW CDC on GPIO 19/20) | +| **Peripheral interfaces** | CAN, RS485, I2C, UART, TF card slot (SPI via CH422G EXIO4), ADC sensor header | +| **Partition scheme** | `app3M_fat9M_16MB` (3 MB app, 9 MB FAT) | +| **Serial baud** | 115200 | +| **Display library** | LovyanGFX (vendored) | +| **Reference** | [waveshare.com/wiki/ESP32-S3-Touch-LCD-4.3](https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-4.3) | + +### RGB bus pin map (Board 3) + +| Signal | GPIOs | +|---|---| +| Red R0–R4 | 1, 2, 42, 41, 40 | +| Green G0–G5 | 39, 0, 45, 48, 47, 21 | +| Blue B0–B4 | 14, 38, 18, 17, 10 | +| DE / VSYNC / HSYNC / PCLK | 5, 3, 46, 7 | + +--- + +## Known unknowns + +These are facts the code references or implies but does not pin down: + +- **PSRAM size on Boards 1 & 2.** The build flag `-DBOARD_HAS_PSRAM` is set for both ESP32-32E targets, but the capacity (typically 4 MB or 8 MB on ESP32-WROOM-32 variants) is never stated in the code or config. Hosyond product pages list some models with PSRAM and some without. +- **Exact screen panel size for Board 1.** The `.crushmemory` file calls it "original 2.8″ ILI9341," but the ILI9341 driver is also used on 2.4″ and 3.2″ panels. No board_config.h comment names the panel size explicitly. +- **Board 1 manufacturer.** The code doesn't name Hosyond for the 2.8″ board the way it does for the 4″. It could be a generic ESP32-32E devkit from any number of vendors. +- **Board 1 SPI MISO pin.** Not defined in `tft_user_setup.h` (only MOSI/SCLK/CS/DC/RST are set). This means SPI read-back from the display may not be wired or used. +- **Serial port path.** All three `board-config.sh` files default to `/dev/ttyUSB0`, which is a Linux convention. The actual development machine appears to be macOS, so the real port (e.g. `/dev/cu.usbserial-*`) is likely overridden at runtime. +- **GT911 I2C address discrepancy (Board 3).** `board_config.h` defines `GT911_ADDR 0x5D` but `LovyanPins.h` configures the touch at address `0x14`. Both are valid GT911 addresses; the runtime address depends on the INT pin state at boot. The code comment says "IMPORTANT: Address 0x14, not 0x5D!" suggesting 0x5D was tried and didn't work. +- **CH422G expander pin mapping (Board 3).** `LovyanPins.h` defines symbolic names (`TP_RST=1`, `LCD_BL=2`, `LCD_RST=3`, `SD_CS=4`, `USB_SEL=5`) but these are CH422G *expander output indices*, not ESP32 GPIOs. The I2C init sequence that drives these pins lives in `DisplayDriverGFX.cpp`, which was not fully inspected. + +## Unknown unknowns + +Things that are plausibly relevant but entirely absent from the codebase: + +- **Power supply specs.** No code references input voltage ranges, regulators, or battery charging circuits, though the Waveshare board has a PH2.0 LiPo header and the Hosyond boards support external lithium batteries with onboard charge management. +- **Thermal limits / operating temperature range.** Not mentioned anywhere. +- **Hardware revision / PCB version.** No version identifiers for any of the three physical boards. +- **Antenna characteristics.** The Waveshare board uses an onboard PCB antenna; the Hosyond boards likely do as well. Gain, radiation pattern, and any shielding considerations are unaddressed. +- **Display viewing angle / brightness / contrast.** The Hosyond 4″ is listed as TN type (narrower viewing angles); the Waveshare 4.3″ is likely IPS but not confirmed in code. +- **ESD / EMC compliance.** No mention of certifications (FCC, CE, etc.). +- **Deep sleep / low-power modes.** The firmware uses `millis()`-based timing and a display-off state, but never enters ESP32 deep sleep. Whether the hardware supports wake-on-touch or wake-on-WiFi is not explored. +- **Audio hardware.** The Hosyond boards support external speakers per their datasheets, and the codebase has no audio code. The Waveshare board does not appear to have onboard audio. +- **SD card.** The Waveshare board has a TF card slot (CS via CH422G EXIO4), and the Hosyond boards have TF card slots as well. The firmware does not use storage. From e4bf8e25b553793cfdbd50b6bf0b29a31e392c7e Mon Sep 17 00:00:00 2001 From: Gene Johnson Date: Sat, 14 Mar 2026 16:04:13 -0700 Subject: [PATCH 2/2] docs: Add questions for the board owner to clarify hardware and feature requirements for `mainline.py` porting. --- klubhaus-doorbell-hardware.md | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/klubhaus-doorbell-hardware.md b/klubhaus-doorbell-hardware.md index 77bb528..d1608c8 100644 --- a/klubhaus-doorbell-hardware.md +++ b/klubhaus-doorbell-hardware.md @@ -134,3 +134,58 @@ Things that are plausibly relevant but entirely absent from the codebase: - **Deep sleep / low-power modes.** The firmware uses `millis()`-based timing and a display-off state, but never enters ESP32 deep sleep. Whether the hardware supports wake-on-touch or wake-on-WiFi is not explored. - **Audio hardware.** The Hosyond boards support external speakers per their datasheets, and the codebase has no audio code. The Waveshare board does not appear to have onboard audio. - **SD card.** The Waveshare board has a TF card slot (CS via CH422G EXIO4), and the Hosyond boards have TF card slots as well. The firmware does not use storage. + +--- + +## Questions for board owner + +I'm looking at porting [mainline.py](mainline.py) — a scrolling terminal news/poetry stream with OTF-font rendering, RSS feeds, ANSI gradients, and glitch effects — to run on one of these boards. To figure out the right approach I need a few things only you can answer: + +### 1. Which board should I target? + +The three boards have very different constraints: + +| | Board 1 (2.8″) | Board 2 (4.0″) | Board 3 (4.3″) | +|---|---|---|---| +| Resolution | 320 × 240 | 320 × 480 | 800 × 480 | +| Display bus | SPI (40 MHz) | SPI (40 MHz) | RGB parallel (14 MHz pclk) | +| Flash | 4 MB | 4 MB | 16 MB | +| PSRAM | unknown | unknown | 8 MB | +| Full-screen redraw | ~60 ms+ | ~120 ms+ | near-instant (framebuffer) | + +Board 3 is the only one with enough RAM and display bandwidth for smooth scrolling with many headlines buffered. Boards 1 & 2 would need aggressive feature cuts. **Which board do you want this on?** + +### 2. PSRAM on your ESP32-32E boards + +The build flags say `-DBOARD_HAS_PSRAM` but I can't tell the capacity. Can you check? Easiest way: + +``` +// Add to setup() temporarily: +Serial.printf("PSRAM size: %d bytes\n", ESP.getPsramSize()); +Serial.printf("Free PSRAM: %d bytes\n", ESP.getFreePsram()); +``` + +If PSRAM is 0 on Boards 1 or 2, those boards can only hold a handful of headlines in 520 KB SRAM (WiFi + TLS eat most of it). + +### 3. Feature priorities + +mainline.py does a lot of things that don't map directly to an ESP32 + TFT. Which of these matter to you? + +- **RSS headline scrolling** — the core experience. How many feeds? All ~25, or a curated subset? +- **OTF font rendering** — mainline uses Pillow to rasterize a custom `.otf` font into half-block characters. On ESP32 this would become either bitmap fonts or a pre-rendered glyph atlas baked into flash. Is the specific font important, or is the aesthetic (large, stylized text) what matters? +- **Left-to-right color gradient** — the white-hot → green → black fade. Easy to replicate in RGB565 on the TFT. Keep? +- **Glitch / noise effects** — the ░▒▓█ and katakana rain. Keep? +- **Mic-reactive glitch intensity** — none of these boards have a microphone. Drop entirely, or substitute with something else (e.g. touch-reactive, or time-of-day reactive)? +- **Auto-translation** — mainline translates headlines for region-specific sources via Google Translate. This requires HTTPS calls that are expensive on ESP32 (~40–50 KB RAM per TLS connection). Keep, pre-translate on a server, or drop? +- **Poetry mode** — fetches full Gutenberg texts. These are large (100+ KB each). Cache to SD card, trim to a small set, or drop? +- **Content filtering** — the sports/vapid regex filter. Trivial to keep. +- **Boot sequence animation** — the typewriter-style boot log. Keep? + +### 4. Network environment + +- Will the board be on a WiFi network that can reach the public internet (RSS feeds, Google Translate, ntfy.sh)? +- Is there a preferred SSID / network, or should it use the existing multi-network setup from the doorbell firmware? + +### 5. SD card availability + +All three boards have TF card slots but the doorbell firmware doesn't use them. A microSD card would be useful for caching fonts, pre-rendered glyph atlases, or translated headline buffers. **Is there an SD card in the board you'd want to target?**