60 lines
2.4 KiB
Markdown
60 lines
2.4 KiB
Markdown
# 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
|