Home

Awesome

ESP_LCD MicroPython driver for ESP32-S3 Devices with ST7789 or compatible displays.

Warning: This work in progress may contain bugs or incorrect documentation.

Overview

This is a driver for MicroPython for devices using the esp_lcd intel 8080 8-bit parallel bus and SPI interfaces. The driver is written in C and is based on devbis' st7789_mpy driver.

I modified the original driver to add the following features:

Pre-compiled firmware

The firmware directory contains pre-compiled MicroPython v1.20.0 firmware compiled using ESP IDF v4.4.4. In addition, the firmware includes the C driver and several frozen Python font files. See the README.md file in the fonts folder for more information about the font files.

Driver API

Note: Curly braces { and } enclose optional parameters and do not imply a Python dictionary.

I80_BUS Methods

SPI_BUS Methods

ESPLCD Methods

The module exposes predefined colors: BLACK, BLUE, RED, GREEN, CYAN, MAGENTA, YELLOW, and WHITE

Hardware Scrolling

The st7789 display controller contains a 240 by 320-pixel frame buffer used to store the pixels for the display. For scrolling, the frame buffer consists of three separate areas: The (tfa) top fixed area, the (height) scrolling area, and the (bfa) bottom fixed area. The tfa is the upper portion of the frame buffer in pixels not to scroll. The height is the center portion of the frame buffer in pixels to scroll. The bfa is the lower portion of the frame buffer in pixels not to scroll. These values control the ability to scroll the entire or a part of the display.

For displays that are 320 pixels high, setting the tfa to 0, height to 320, and bfa to 0 will allow scrolling of the entire display. To scroll a portion of the display, you can set the tfa and bfa to a non-zero value. tfa + height + bfa = should equal 320; otherwise, the scrolling mode is undefined.

Displays less than 320 pixels high, the tfa, height, and bfa must be adjusted to compensate for the smaller LCD panel. The actual values will vary depending on the configuration of the LCD panel. For example, scrolling the entire 135x240 TTGO T-Display requires a tfa value of 40, height value of 240, and bfa value of 40 (40+240+40=320) because the T-Display LCD shows 240 rows starting at the 40th row of the frame buffer, leaving the last 40 rows of the frame buffer undisplayed.

Other displays, like the Waveshare Pico LCD 1.3-inch 240x240 display, require the tfa set to 0, height set to 240, and bfa set to 80 (0+240+80=320) to scroll the entire display. The Pico LCD 1.3 shows 240 rows starting at the 0th row of the frame buffer, leaving the last 80 rows undisplayed.

The vscsad method sets the (VSSA) Vertical Scroll Start Address. The VSSA sets the line in the frame buffer that will be the first line after the tfa.

The ST7789 datasheet warns:

The value of the vertical scrolling start address is absolute (with referenceto the frame memory), it must not enter the fixed area defined by Vertical Scrolling Definition, otherwise undesirable image will be displayed on the panel.

Helper functions

Building the firmware

See the MicroPython Getting Started page for more detailed information on building the MicroPython firmware.

Clone the Repositories

git clone git@github.com:micropython/micropython.git
git clone https://github.com/russhughes/s3lcd.git

Compile the cross compiler if you haven't already

make -C micropython/mpy-cross

ESP32 MicroPython 1.14 thru 1.19

Change to the ESP32 port directory

cd micropython/ports/esp32

Compile the module with specified USER_C_MODULES dir

make USER_C_MODULES=../../../../s3lcd/src/micropython.cmake clean submodules all

Erase the target device if this is the first time uploading this firmware

make USER_C_MODULES=../../../../s3lcd/src/micropython.cmake erase

Upload the new firmware

make USER_C_MODULES=../../../../s3lcd/src/micropython.cmake deploy

ESP32 MicroPython 1.20 and later

Change to the ESP32 port directory, and build the firmware

cd micropython/ports/esp32

make \
    BOARD=ESP32_GENERIC \
    BOARD_VARIANT=SPIRAM \
    USER_C_MODULES=../../../../s3lcd/src/micropython.cmake \
    FROZEN_MANIFEST=../../../../s3lcd/manifest.py \
    clean submodules all

Erase the flash and deploy on your device

make \
    BOARD=ESP32_GENERIC \
    BOARD_VARIANT=SPIRAM \
    USER_C_MODULES=../../../../s3lcd/src/micropython.cmake \
    FROZEN_MANIFEST=../../../../s3lcd/manifest.py \
    erase deploy

RP2040 MicroPython 1.20 and later

Change to the RP2 port directory, and build the firmware

cd micropython/ports/rp2
make \
    BOARD=RPI_PICO \
    FROZEN_MANIFEST=../../../../gc9a01c/manifest.py \
    USER_C_MODULES=../../../gc9a01c/src/micropython.cmake \
    clean submodules all

Flash the firmware.uf2 file from the build-${BOARD} directory to your device.

Thanks go out to:

-- Russ