Proof of concept: 2bpp greyscale LVGL display

2026-05-06 13:53:55 -07:00
commit d91fb65381
12 changed files with 6895 additions and 0 deletions
@@ -0,0 +1,59 @@
+# Waveshare 2.9" E-Paper LVGL Project
+
+## Goal Summary
+- Extend the native waveshare_epaper component of esphome to support 2-bit grayscale
+- Only concerned with this one target board: `2.90inv2-r2`
+
+## Hardware
+- ESP32-WROOM-32 (nodemcu-32s board)
+- Waveshare 2.9inch Touch ePaper HAT (296x128, 2-bit grayscale)
+- Display model string: `2.90inv2-r2` (SSD1680 controller)
+- Pin mapping: SCLK=GPIO23, MOSI=GPIO22, CS=GPIO19, DC=GPIO18, BUSY=GPIO4, RST=GPIO5
+
+## Software
+- ESPHome 2026.1.0
+- Framework: esp-idf
+- Project directory: ~/Projects/waveshare-panel
+
+## Current Status
+- Display working correctly via ESPHome's native display library
+- LVGL rendering confirmed working (black background visible)
+- Custom component `waveshare_epaper_2bit` created and flashed, working identically to built-in driver
+- Custom model name: `2.90inv2-r2-2bpp`
+
+## Known Issues / Quirks
+- LVGL color depth is hardcoded to 16-bit (RGB565) in ESPHome — only supported value
+- Display renders in 1-bit monochrome despite panel supporting 2-bit grayscale
+- Colors are inverted by default (bg_color: 0x000000 produces white background)
+- Resolved: original timeout errors were caused by on_draw_end hammering the display
+
+## Working LVGL Config
+- refer to the file waveshare-test.yaml
+
+## Goal: 2-bit Grayscale Support
+The SSD1680 controller supports 4-shade grayscale via two bitplanes:
+- Register 0x24: bitplane 1
+- Register 0x26: bitplane 2
+
+| 0x24 | 0x26 | Result     |
+|------|------|------------|
+| 1    | 1    | White      |
+| 1    | 0    | Light grey |
+| 0    | 1    | Dark grey  |
+| 0    | 0    | Black      |
+
+The ESPHome driver only writes to 0x24, discarding grayscale information.
+The real problem is upstream — RGB565 is converted to 1-bit before display() is
+called, so grayscale data is lost before the driver even sees it. Next step is to
+find where this conversion happens in the ESPHome display pipeline so the patch
+can preserve grayscale information through to the two-bitplane write.
+
+## Relevant Files
+- Custom component: `custom_components/waveshare_epaper_2bit/`
+  - `__init__.py` — CODEOWNERS only
+  - `display.py` — component schema and model registration
+  - `waveshare_epaper_2bit.cpp` — driver implementation
+  - `waveshare_epaper_2bit.h` — header
+- Build cache: `.esphome/build/waveshare-epaper-test/src/esphome/components/`
+- ESPHome source (venv): ~/Code/esphome-2026.1.0/
+- Applicable ESPHome source is copied into .esphome/build by the build system at compile time