waveshare-panel/CLAUDE.md

Waveshare 2.9" E-Paper LVGL Project

Goal Summary

• Waveshare 2.9" Touch ePaper HAT driving LVGL UI via ESPHome on ESP32
• 2-bit grayscale display support implemented via custom ESPHome component
• Touchscreen integration in progress

Hardware

• ESP32-WROOM-32 (nodemcu-32s board)
• Waveshare 2.9inch Touch ePaper HAT (296x128, SSD1680 display, GT1151 touchscreen)

Pin Mapping

Function	ESP Pin	HAT Pin
Display SCLK	GPIO18	Pin23/GPIO11/SPI0_SCLK
Display MOSI	GPIO23	Pin19/GPIO10/SPI0_MOSI
Display CS	GPIO19	Pin24/GPIO8/SPI0_CE0
Display DC	GPIO17	Pin22/GPIO25
Display BUSY	GPIO4	Pin24/GPIO24
Display RST	GPIO5	Pin11/GPIO17/SPI1_CE1
Touch SDA	GPIO21	Pin3/GPIO2/I2C1_SDA
Touch SCL	GPIO22	Pin5/GPIO3/I2C1_SCL
Touch RST	GPIO15	Pin13/GPIO27
Touch INT	GPIO16	Pin15/GPIO22

Note: GPIO15 (Touch RST) is an ESP32 strapping pin, but only affects boot log output (LOW silences it). No impact on UART download mode or OTA flashing.

Software

• ESPHome 2026.1.0
• Framework: esp-idf
• Project directory: ~/Projects/waveshare-panel

Current Status

• 2-bit grayscale fully working via custom component waveshare_epaper_2bit
• LVGL rendering working, 4-shade colorspace confirmed
• Bayer ordered dithering implemented for gradient smoothing
• Touchscreen working: polling mode, portrait-orientation transform confirmed correct
• LVGL touch input and button state working end-to-end
• Panel now mounted vertically (portrait); 4-row layout for light/fan controls
• Active: LVGL layout work

Display Refresh Pattern

Two-tier refresh wired to lvgl.on_draw_end via two mode: restart scripts:

• Partial (refresh_display, 80ms then a 350ms retry): calls display_partial() — fast 1-bit, non-blocking, immediate interaction feedback
• Full (full_refresh_display, 10s): calls component.update: display0 → display() — full 2-bit grayscale quality restore after idle

The retry exists because display_partial() silently drops calls when the e-paper is still busy from a previous refresh (waveshare_epaper_2bit.cpp ~line 2003). Without it, HA-triggered widget updates (e.g. fan speed sync arriving 200-500ms after a tap) could land during the busy window of the tap's partial refresh and be lost until the 10s full refresh. The retry fires ~430ms after the last draw, by which point the e-paper's ~300ms partial cycle has cleared. mode: restart cancels the retry if a new draw arrives, so it only fires in the quiet period.

component.update: display0 only pushes the frame buffer to hardware and does not re-trigger on_draw_end.

Grayscale Implementation

Custom component model name: 2.90inv2-r2-2bpp

Key implementation details:

• Gray4 waveform LUT loaded via register 0x32 on every display() call
• Activation uses 0xC7 (custom LUT), not 0xF7 (which reloads OTP LUT)
• display() = full 2-bit grayscale refresh; display_partial() = fast 1-bit partial refresh
• Second bitplane buffer (buffer2_) allocated in initialize()

Confirmed bitplane table for this panel with Gray4 LUT:

0x24	0x26	Result
0	0	White
1	0	Light grey
0	1	Dark grey
1	1	Black

Color convention: 0xFFFFFF=white, 0x000000=black (no inversion). LVGL 4-shade palette: 0xFFFFFF, 0xAAAAAA, 0x555555, 0x000000

Dithering: 4×4 Bayer ordered dither, bias = bayer*2 - 15 (±15 range). Amplitude chosen to keep 0xAAAAAA and 0x555555 as solid fills.

Touchscreen

• Controller: ICNT86X (I2C address 0x48; 0x30 also ACKs, likely DFU/bootloader interface)
• Custom component: custom_components/icnt86x/ (ESPHome has no native ICNT86X driver)
• Touch count at register 0x1001, touch data at 0x1002 (7 bytes/point), clear by writing 0x00 to 0x1001
• Waveshare's own driver inverts both axes: X = 295 - raw_x, Y = 127 - raw_y
• INT pulse is very brief (sub-ms); component works in polling mode regardless
• Coordinate transform (portrait, display rotation 0°): swap_xy: true, mirror_x: true, calibration x_max: 127, y_max: 295. Gotcha: ESPHome's base class applies swap_xy before calibration normalization (see touchscreen.cpp::add_raw_touch_position_), so calibration x_max/y_max must describe the post-swap range — i.e., match the display width/height, not the raw sensor's native axes.

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
• Main config: waveshare-test.yaml (pin table here is source of truth)
• Build cache: .esphome/build/waveshare-epaper-test/src/esphome/components/
• ESPHome venv (Windows): C:\Projects\python_virtual\esphome-2026.1.0 (activate before esphome commands)
• ESPHome source (WSL venv): ~/Code/esphome-2026.1.0/