waveshare-panel/CLAUDE.md

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