Setting up Waveshare ESP32-S3-Touch-LCD-7 board, 800 x 480

[MarkMakies]

It took me forever to get this going, so just in case you have one of these and need some basic help, here it is. If I had this info when I started it would have saved me days. Nothing here is perfected, but it works. Most of this has been posted by others, but this brings it all together which worked for me.

Note I haven't been able to get touch to work. I think there is a conflict with pins 8 & 9 and I won't be trying as I dont need to use it for my application.

This is specific to the Waveshare ESP32-S3-Touch-LCD-7 board, 800 x 480, ESP32-S3-WROOM-1 (N8R8) 8MB PSRAM, 8MB Flash, ST7262 display driver, GT911 touch driver.
(https://www.waveshare.com/wiki/ESP32-S3-Touch-LCD-7#Overview)

I used the following to build and flash

git clone https://github.com/lvgl-micropython/lvgl_micropython
cd lvgl_micropython

python3 make.py esp32 BOARD=ESP32_GENERIC_S3 BOARD_VARIANT=SPIRAM_OCT DISPLAY=rgb_display INDEV=gt911 --flash-size=8 --enable-uart-repl=y

/home/mark/.espressif/python_env/idf5.2_py3.12_env/bin/python -m esptool --chip esp32s3 -p /dev/ttyACM0 -b 460800 --before default_reset --after hard_reset write_flash --flash_mode dio --flash_size 8MB --flash_freq 80m --erase-all 0x0 /home/mark/Projects/LVGL/lvgl_micropython/build/lvgl_micropy_ESP32_GENERIC_S3-SPIRAM_OCT-8.bin

On boot REPL shows: Version: LVGL (9.2.2) MicroPython (1.24.1) Binding compiled on 2025-04-26; Generic ESP32S3 module with Octal-SPIRAM with ESP32S3

Setup code

(touch components commented out)

print('Starting Micropython-LVGL-Waveshare-7inch-Display (Advanced Build) ************************* 2 seconds to abort!')
from time import sleep_ms
sleep_ms(2000)

#from i2c import I2C
#import gt911
import lcd_bus
import rgb_display
import lvgl as lv
import task_handler

WIDTH = 800
HEIGHT = 480
BUFFER_SIZE = 768000

#i2c_bus = I2C.Bus(host=1, scl=9, sda=8, freq=400000, use_locks=False)
#touch_device = I2C.Device(i2c_bus, dev_id=gt911.I2C_ADDR, reg_bits=gt911.BITS)

bus = lcd_bus.RGBBus(
    hsync=46, vsync=3, de=5, pclk=7,
    data0=14, data1=38, data2=18, data3=17, data4=10, 
    data5=39, data6=0, data7=45,data8=48, data9=47, data10=21, 
    data11=1, data12=2, data13=42, data14=41, data15=40,

    freq=13000000,
    hsync_front_porch=4, hsync_back_porch=4, hsync_pulse_width=2, hsync_idle_low=False,
    vsync_front_porch=4, vsync_back_porch=4, vsync_pulse_width=2, vsync_idle_low=False,
    de_idle_high=False, pclk_idle_high=False, pclk_active_low=False)

buf1 = bus.allocate_framebuffer(BUFFER_SIZE, lcd_bus.MEMORY_SPIRAM)
buf2 = bus.allocate_framebuffer(BUFFER_SIZE, lcd_bus.MEMORY_SPIRAM)

display = rgb_display.RGBDisplay(
    data_bus=bus, 
    display_width=WIDTH, 
    display_height=HEIGHT,
    frame_buffer1=buf1,
    frame_buffer2=buf2,
    color_space=lv.COLOR_FORMAT.RGB565,
    rgb565_byte_swap=False)

display.set_power(True)
display.init()
display.set_backlight(100)

"""indev = gt911.GT911(touch_device)
if indev.hw_size != (_WIDTH, _HEIGHT):
    fw_config = indev.firmware_config
    fw_config.width = _WIDTH
    fw_config.height = _HEIGHT
    fw_config.save()
    del fw_config
"""

scrn = lv.screen_active()
scrn.set_style_bg_color(lv.color_hex(0x000000), 0)

task_handler.TaskHandler()

And used this code to test stability and colour

color_values = [0, 63, 191, 255]
buttons = []
btn_w = 90
btn_h = 50
cols = len(color_values) ** 2
x = 0
y = 0

for ri, r in enumerate(color_values):
    for gi, g in enumerate(color_values):
        for bi, b in enumerate(color_values):

            btn = lv.button(scrn)
            btn.set_size(btn_w, btn_h)
            btn.set_style_bg_color(lv.color_make(r, g, b), lv.PART.MAIN)

            btn.set_pos(x * (btn_w + 10), y * (btn_h + 10))

            label = lv.label(btn)
            hex_text = '{:02X}{:02X}{:02X}'.format(r, g, b)
            label.set_text(hex_text)

            x += 1
            if x >= 8:   # 8 buttons per row (
                x = 0
                y += 1

Hopefully you see this...

Wi-Fi / MQTT

I specifically use this display to chart some MQTT telemetry. My data points come in every 1 minute and I show the last 600 points, corresponding to 10 hours.

import network
from umqtt.simple import MQTTClient

SSID      = 'BlackNightOffice'
PW        = 'XXXXXX'
BROKER    = '192.168.2.100'
USER      = 'mymqtt'
PASSWD    = 'XXXXXX'
CID       = b'Display2'
TOPIC     = b'Sensor/stat/DATA'

print('Connecting to WiFi...')
sta = network.WLAN(network.STA_IF)
sta.active(True)
if not sta.isconnected():
    sta.connect(SSID, PW)
    while not sta.isconnected():
        sleep_ms(200)

print('Connected to WiFi:', sta.ifconfig())

print('Setup Chart')
PTS       = 600
YMIN, YMAX= 0, 100
CLR       = lv.palette_main(lv.PALETTE.BLUE)

chart = lv.chart(scrn)
chart.set_size(780, 420)
chart.center()
chart.set_type(lv.chart.TYPE.LINE)
chart.set_range(lv.chart.AXIS.PRIMARY_Y, YMIN, YMAX)
chart.set_point_count(PTS)
chart.set_update_mode(lv.chart.UPDATE_MODE.SHIFT)

ser = chart.add_series(CLR, lv.chart.AXIS.PRIMARY_Y)

label = lv.label(scrn)
label.align_to(chart, lv.ALIGN.OUT_BOTTOM_MID, 0, 10)
label.set_text('-- %')

for _ in range(PTS):
    chart.set_next_value(ser, 0)

print('Connecting to MQTT broker...')

def cb(topic, msg):
    if topic == TOPIC:
            v = max(YMIN, min(YMAX, int(round(float(msg)))))
            chart.set_next_value(ser, v)
            label.set_text(f'10 hours     {v} %')
            chart.refresh()

cli = MQTTClient(CID, BROKER, user=USER, password=PASSWD)
cli.set_callback(cb)
cli.connect()
cli.subscribe(TOPIC)

while True:
    try:
        cli.check_msg()
    except OSError:
        sleep_ms(1000)
        try:
            cli.connect()
            cli.subscribe(TOPIC)
        except Exception:
            pass
    sleep_ms(20)

[kdschlosser]

the display is stable with the original parameters you have to dial down the frequency to 13 mhz on the bus. otherwise the UI starts to walk across the display. You are able to turn it up because you are overclocking the SPI RAM so it is able to run faster.

[MarkMakies]

Tested with original params and 13 MHz - all good. Thanks Kevin.

[kdschlosser]

no worries m8. I have tried to make the library as flexible as possible due to there being so many variations of driver IC's touch IC's and panels that are used. Just because one display has the same resolution, same touch panel and same driver IC doesn't mean they will have the same setup parameters and function in the same manner. Quite a few driver IC's support more than one way to connect an MCU to it but also panels are not all made the same either and that means it may have different parameters that have to be set with the display IC.

The binding is going to be slower than running a UI using only C code. That is the nature of Python in general. There is a trade off for not having to manage memory and releasing resources and that costs speed and RAM use. This is the reason why you need to lower the frequency of the RGB connection. If running using C code only and there isn't a lot of processor use then you can get the frequency turned up to 16 mhz without over clocking the SPIRAM. Due to running MicroPython that has to be slowed down a bit. I can tell you that it is the fastest RGB driver that has been written hands down. The RGB driver running in Python code is faster than the C driver written by the folks over at Espressif.

You can overclock the SPIRAM if you like and I do recommend you do it because of the additional performance you get when reading and writing to SPIRAM. It is going to cause the MCU to use more power but I don't believe that is so much of an issue considering the display panel that is being used. When more power is drawn guess what happens? More heat gets created, I do strongly suggest sticking a heat sink onto the ESP32 to help shed the added heat. Nothing fancy just a simple aluminum heat sink with a couple of fins and is 3/8" tall at most. User thermal tape to "glue" it to the ESP32. Then you can overclock it and know that it is going to run without having any seemingly random problems happen.

[MarkMakies]

the display is stable with the original parameters you have to dial down the frequency to 13 mhz on the bus. otherwise the UI starts to walk across the display. You are able to turn it up because you are overclocking the SPI RAM so it is able to run faster.

I'm not sure if this is related, but after many hours of running I've found the UI is 'crawling' across the display. It is slowly 'wrapping' around. ie what was on the right is starting to appear on the left. The rate is about 3 pixels of shift per hour. I would not have thought the PCLK frequency would be responsible as the drift is so slow. There is no glitching or instability in the display. It is almost like a counter is slipping/missing a count every now and then causing this creeping misalignment.

I'm plotting three charts that update every 5 minutes, and I'm also displaying a clock label that updates every 1 sec.

I'm wondering is there anything I can do to 'reset' the buffers, if indeed that is the problem.

[kdschlosser]

drop the frequency another 500khz down to 12.5mhz if that doesn't do ya then go up by 500khz...

It's the clock speed for sure. You have to mess with it to find that sweet spot for the combination of hardware. It's a really annoying thing to have to tinker about with. what you can do is you can set it up so you can adjust it from the UI and use the esp32 NVS to store the setting in NVRAM. the stetting would take effect after a hard reset of the ESP32 but at least you won't have to keep on flashing the firmware to get it done.

[kdschlosser]

what is actually happening is the shift occurs each time the buffer gets swapped out. You can give it a kick in the as to really get it moving if you do something like have a simply slider widget that you have some looping code that changes the value of the slider at a really high rate of speed. Just make sure to call lv.refr_now after you change the value because the main thread is going to be tied up which is not going to allow lv_task_handler to get called.

[MarkMakies]

Ok, I have a definitive PCLK frequency (MHz) sweet spot for this board: 12.9 Mhz

• <= 12.8 blank display
• = 12.9 rock solid for 24 hours
• >=13.0 starts walking right, about 3 pixels per hour (at 13)
• >= 13.5 starts walking right, pixels per minute