Waveshare ESP32-S3-LCD-Driver-Board with 2.8" round RGB LCD (480×480 ST7701S, GT911)

# ESP Screens - Waveshare ESP32-S3-LCD-Driver-Board with the 2.8-inch round 480 x 480 panel (ST7701S over RGB) and
# GT911 capacitive touch, experimental: an ESP32-S3-WROOM-1-N8R8 (8 MB flash, 8 MB octal PSRAM) and a TCA9554 expander
# that carries the panel's reset, the touch panel's reset and a backlight enable that does nothing. Waveshare sold the
# board with this panel (and with 2.1-inch round and 4-inch square RGB panels) as a kit no longer listed; the board
# alone is still sold, its current examples for SPI panels only. Not the ESP32-S3-Touch-LCD-2.8B (480 x 640).
# docs/WAVESHARE28R.md says what has been tried on the glass.
#
# Round glass: the 2.8 inches are the circle's diameter, which is the panel's 480 px width, so the density is
# 480 / 2.8 = 171 dpi, the standard look's own. The firmware lays out a square; the circle cuts its corners, so the
# grid is inset to the largest square inside the circle (480 / sqrt 2 = 339 px, 70 px a side), and the top bar with
# it (HEADER_INSET follows GRID_MARGIN). The page bar's chevrons still fall outside the circle; the page dots and the
# edge swipe change pages.
#
# A board file is the board's hardware, the facts the shared tree takes from it (its glass and its grid), and the
# features it has; docs/PROFILES.md says how the files of a screen fit together. Two entry files include this one:
# checkout/waveshare28r.yaml (a build on this computer) and packages/waveshare28r.yaml (the package a screen builds
# from over GitHub).
packages:
  hardware: !include ../hardware/esp32s3-rgb.yaml
  # The compact look (the CYD's sizes in millimetres): the square inside the circle is 50 mm, smaller than a CYD's glass.
  look: !include ../looks/compact.yaml
  touch: !include ../features/capacitive-touch.yaml
  backlight: !include ../features/backlight.yaml
  # The backlight cannot be dimmed or switched off from software on this board (below), so no standby and no night.
  backlight_always_on: !include ../features/backlight-always-on.yaml
  camera: !include ../features/camera.yaml
  self_test: !include ../features/self-test.yaml

substitutions:
  BOARD_ID: "waveshare28r"
  DEVICE_NAME: "waveshare28r-new"
  DEVICE_FRIENDLY_NAME: "My Waveshare 2.8 Round"

  PANEL_W: "480"
  PANEL_H: "480"
  # 480 / 2.8: on round glass the diameter is the width. Its own preview renderer carries GRID_MARGIN below.
  DISPLAY_DPI: "171.429"
  # The square inside the circle is 50 x 50 mm: two columns of three cells under the top bar, as on the CYD.
  GRID_COLS: "2"
  GRID_ROWS: "3"
  # A fixed inset to the inscribed square: it gives up the circle's edges, which a round-aware layout could use.
  GRID_MARGIN: "70"
  # The page bar as tall as the margin, so the tile area ends inside the square too (480 - 70 = 410).
  PAGE_BAR_H: "70"
  SCREEN_MAX_TILES: "128"
  SCREEN_MAX_PAGES: "24"
  SCREEN_MAX_BAR_ITEMS: "12"
  LVGL_BUFFER_SIZE: "25%"
  BACKLIGHT_DIMMABLE: "false"

# ============================================================
# No need to edit below this line.
# ============================================================

esp32:
  flash_size: 8MB

logger:
  # The board's console is the chip's own USB (Serial/JTAG).
  hardware_uart: USB_SERIAL_JTAG

i2c:
  id: touch_bus
  sda: GPIO15
  scl: GPIO7
  frequency: 400kHz
  scan: true

# TCA9554 (PCA9554 registers). Schematic EXIOn is `number: n-1`: 0 TP_RST, 1 BL_EN, 2 LCD_RST.
pca9554:
  - id: expander
    address: 0x20
    i2c_id: touch_bus

# The ST7701S's three-wire setup bus; it runs once at boot, the picture goes over the RGB pins.
spi:
  id: lcd
  clk_pin: GPIO2
  mosi_pin: GPIO1
  interface: spi3

output:
  # The backlight is lit whatever the firmware does: GPIO6 PWM over its whole range and BL_EN (expander 1) held low
  # both left it fully on (measured 2026-09-20). The features need an output by this name, so it writes nothing.
  - platform: template
    id: gpio_backlight_pwm
    type: float
    write_action:
      - lambda: '(void) state;'
  # Holds LCD_RST (expander 2, active low) released: setup turns an output off, and inverted off is high. No
  # esphome: on_boot: here (tools/check_packages.py); nothing needs to touch it after setup.
  - platform: gpio
    id: lcd_reset_released
    pin:
      pca9554: expander
      number: 2
      inverted: true

touchscreen:
  - platform: gt911
    id: ts_touch
    i2c_id: touch_bus
    display: my_display
    update_interval: 20ms
    interrupt_pin: GPIO16
    reset_pin:
      pca9554: expander
      number: 0  # TP_RST (schematic EXIO1)

# st7701s, not mipi_rgb: ESPHome 2026.10's mipi_rgb puts a software reset (0x01) in front of the init sequence when no
# reset_pin is set, and on this panel that left blue and green vertical streaks (2026-11-08). mipi_rgb was only seen
# working here on 2026.7.4, without that reset; st7701s on 2026.10.2 sends the vendor sequence as is and draws.
# Pins, porches and init sequence are Waveshare's (2.8inch_RGB_LCD demo, main.c and ESP_Panel_Board_Custom.h agree).
display:
  - platform: st7701s
    id: my_display
    spi_id: lcd
    spi_mode: MODE1
    data_rate: 10MHz
    dimensions:
      width: ${PANEL_W}
      height: ${PANEL_H}
    pclk_frequency: 16MHz
    # ESPHome's default (true) is the opposite edge to the vendor's.
    pclk_inverted: false
    # The vendor's porches. ESPHome's defaults make widgets jump on this panel.
    hsync_pulse_width: 8
    hsync_back_porch: 10
    hsync_front_porch: 50
    vsync_pulse_width: 2
    vsync_back_porch: 18
    vsync_front_porch: 8
    # bgr on st7701s (it swaps the pin groups and sets MADCTL, which cancel); rgb would be the mipi_rgb equivalent.
    color_order: bgr
    cs_pin: GPIO42
    de_pin: GPIO40
    hsync_pin: GPIO38
    vsync_pin: GPIO39
    pclk_pin: GPIO41
    data_pins:
      red: [GPIO46, GPIO3, GPIO8, GPIO18, GPIO17]
      green: [GPIO14, GPIO13, GPIO12, GPIO11, GPIO10, GPIO9]
      blue: [GPIO5, GPIO45, GPIO48, GPIO47, GPIO21]
    update_interval: never
    auto_clear_enabled: false
    init_sequence:
      - [ 0xFF, 0x77, 0x01, 0x00, 0x00, 0x13 ]
      - [ 0xEF, 0x08 ]
      - [ 0xFF, 0x77, 0x01, 0x00, 0x00, 0x10 ]
      - [ 0xC0, 0x3B, 0x00 ]
      - [ 0xC1, 0x10, 0x0C ]
      - [ 0xC2, 0x07, 0x0A ]
      - [ 0xC7, 0x00 ]
      - [ 0xCC, 0x10 ]
      - [ 0xCD, 0x08 ]
      - [ 0xB0, 0x05, 0x12, 0x98, 0x0E, 0x0F, 0x07, 0x07, 0x09, 0x09, 0x23, 0x05, 0x52, 0x0F, 0x67, 0x2C, 0x11 ]
      - [ 0xB1, 0x0B, 0x11, 0x97, 0x0C, 0x12, 0x06, 0x06, 0x08, 0x08, 0x22, 0x03, 0x51, 0x11, 0x66, 0x2B, 0x0F ]
      - [ 0xFF, 0x77, 0x01, 0x00, 0x00, 0x11 ]
      - [ 0xB0, 0x5D ]
      - [ 0xB1, 0x3E ]
      - [ 0xB2, 0x81 ]
      - [ 0xB3, 0x80 ]
      - [ 0xB5, 0x4E ]
      - [ 0xB7, 0x85 ]
      - [ 0xB8, 0x20 ]
      - [ 0xC1, 0x78 ]
      - [ 0xC2, 0x78 ]
      - [ 0xD0, 0x88 ]
      - [ 0xE0, 0x00, 0x00, 0x02 ]
      - [ 0xE1, 0x06, 0x30, 0x08, 0x30, 0x05, 0x30, 0x07, 0x30, 0x00, 0x33, 0x33 ]
      - [ 0xE2, 0x11, 0x11, 0x33, 0x33, 0xF4, 0x00, 0x00, 0x00, 0xF4, 0x00, 0x00, 0x00 ]
      - [ 0xE3, 0x00, 0x00, 0x11, 0x11 ]
      - [ 0xE4, 0x44, 0x44 ]
      - [ 0xE5, 0x0D, 0xF5, 0x30, 0xF0, 0x0F, 0xF7, 0x30, 0xF0, 0x09, 0xF1, 0x30, 0xF0, 0x0B, 0xF3, 0x30, 0xF0 ]
      - [ 0xE6, 0x00, 0x00, 0x11, 0x11 ]
      - [ 0xE7, 0x44, 0x44 ]
      - [ 0xE8, 0x0C, 0xF4, 0x30, 0xF0, 0x0E, 0xF6, 0x30, 0xF0, 0x08, 0xF0, 0x30, 0xF0, 0x0A, 0xF2, 0x30, 0xF0 ]
      - [ 0xE9, 0x36, 0x01 ]
      - [ 0xEB, 0x00, 0x01, 0xE4, 0xE4, 0x44, 0x88, 0x40 ]
      - [ 0xED, 0xFF, 0x10, 0xAF, 0x76, 0x54, 0x2B, 0xCF, 0xFF, 0xFF, 0xFC, 0xB2, 0x45, 0x67, 0xFA, 0x01, 0xFF ]
      - [ 0xEF, 0x08, 0x08, 0x08, 0x45, 0x3F, 0x54 ]
      - [ 0xFF, 0x77, 0x01, 0x00, 0x00, 0x00 ]
      - delay 120ms
      - [ 0x11 ]
      - delay 120ms
      - [ 0x3A, 0x66 ]
      - [ 0x36, 0x00 ]
      - [ 0x35, 0x00 ]
      - [ 0x20 ]
      - delay 120ms
      - [ 0x29 ]