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:

• Support for esp-idf ESP_LCD intel 8080 parallel and SPI interfaces using DMA.
• Display framebuffer enabling alpha blending for many drawing methods.
• Display Rotation.
• Hardware Scrolling.
• Writing text using fonts converted from True Type fonts.
• Drawing text using eight and 16-bit wide bitmap fonts, including 12 bitmap fonts derived from classic pc text mode fonts.
• Drawing text using 26 included Hershey vector fonts.
• Drawing JPGs using the TJpgDec - Tiny JPEG Decompressor R0.01d. from http://elm-chan.org/fsw/tjpgd/00index.html.
• Drawing PNGs using the pngle library from https://github.com/kikuchan/pngle.
• Writing PNGs from the framebuffer using the PNGenc library from https://github.com/bitbank2/PNGenc
• Drawing and rotating Polygons and filled Polygons.
• Several example programs. The example programs require a tft_config.py module to be present. Some examples require a tft_buttons.py module as well. You may need to modify the tft_buttons.py module to match the pins your device uses.
• tft_config.py and tft_buttons.py configuration examples are provided for:
  • ESP32S3-BOX and BOX-Lite
  • LilyGo T-Display-S3
  • LilyGo T-Dongle-S3
  • LilyGo T-Embed
  • LilyGo T-HMI
  • LilyGo T-QT Pro
  • Seeed Studio WT32-SC01 Plus
  • M5STACK ATOM-S3
  • M5STACK CORES3
  • BananaPi BPI-Centi-S3

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

• s3lcd.I80_BUS(data, dc, wr, {rd, cs, pclk, bus_width, lcd_cmd_bits, lcd_param_bits, dc_idle_level, dc_cmd_level, dc_dummy_level, dc_data_level, cs_active_high, reverse_color_bits, swap_color_bytes, pclk_active_neg, pclk_idle_low})

  This method sets the interface configuration of an intel 8080 parallel bus for the ESPLCD driver. The ESPLCD driver will automatically initialize and deinitialize the I80 bus.

  Required Parameters:

  • data tuple of pin numbers attached to the data bus in least to most significant bit order
  • dc data/command pin number
  • wr write pin number

  Optional Parameters:

  • rd read pin number
  • cs chip select pin number
  • pclk pixel clock frequency in Hz
  • bus_width bus width in bits
  • lcd_cmd_bits number of bits used to send commands to the LCD
  • lcd_param_bits number of bits used to send parameters to the LCD
  • dc_idle_level D/C pin level when idle
  • dc_cmd_level D/C pin level when sending commands
  • dc_dummy_level D/C pin level when sending dummy data
  • dc_data_level D/C pin level when sending data
  • cs_active_high CS pin level when active
  • reverse_color_bits reverse the order of color bits
  • swap_color_bytes swap the order of color bytes
  • pclk_active_neg pixel clock is active negative
  • pclk_idle_low pixel clock is idle low

SPI_BUS Methods

• s3lcd.SPI_BUS(spi_host, sck, mosi, dc, {cs, spi_mode, pclk, lcd_cmd_bits, lcd_param_bits, dc_idle_level, dc_as_cmd_phase, dc_low_on_data, octal_mode, lsb_first, swap_color_bytes})

  This method sets the interface configuration of an SPI bus for the ESPLCD driver. The ESPLCD driver will automatically initialize and deinitialize the SPI bus.

  Required Parameters:

  • spi_host SPI host to use.
  • sck sck pin number
  • mosi MOSI pin number
  • dc D/C pin number

  Optional Parameters:

  • cs CS pin number
  • spi_mode Traditional SPI mode (0~3)
  • pclk Frequency of pixel clock
  • lcd_cmd_bits Bit-width of LCD command
  • lcd_param_bits Bit-width of LCD parameter
  • dc_idle_level D/C pin level when idle
  • dc_as_cmd_phase D/C line value is encoded into SPI transaction command phase
  • dc_low_on_data If this flag is enabled, D/C line = 0 means transfer data, D/C line = 1 means transfer command
  • octal_mode transmit using octal mode (8 data lines)
  • lsb_first transmit LSB bit first
  • swap_color_bytes (bool) Swap data byte order

ESPLCD Methods

• s3lcd.ESPLCD(bus, width, height, {reset, rotations, rotation, inversion, dma_rows, options})

  Required positional arguments:

  • bus I80_BUS or SPI_BUS object
  • width display width
  • height display height

  Optional keyword arguments:

  • reset reset pin number

  • rotations Creates a custom rotation table. A rotation table is a list of tuples for each rotation containing the width, height, x_gap, y_gap, swap_xy, mirror_x, and mirror_y values for each rotation.

    Default rotations are included for the following display sizes:

    | Display | Default Orientation Tables | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 320x480 | ((320, 480, 0, 0, false, true, false), (480, 320, 0, 0, true, false, false), (320, 480, 0, 0, false, false, true), (480, 320, 0, 0, true, true, true)) | | 240x320 | ((240, 320, 0, 0, false, false, false), (320, 240, 0, 0, true, true, false), (240, 320, 0, 0, false, true, true), (320, 240, 0, 0, true, false, true)) | | 170x320 | ((170, 320, 35, 0, false, false, false), (320, 170, 0, 35, true, true, false), (170, 320, 35, 0, false, true, true), (320, 170, 0, 35, true, false, true)) | | 240x240 | ((240, 240, 0, 0, false, false, false), (240, 240, 0, 0, true, true, false), (240, 240, 0, 80, false, true, true), (240, 240, 80, 0, true, false, true)) | | 135x240 | ((135, 240, 52, 40, false, false, false), (240, 135, 40, 53, true, true, false), (135, 240, 53, 40, false, true, true), (240, 135, 40, 52, true, false, true)) | | 128x160 | ((128, 160, 0, 0, false, false, false), (160, 128, 0, 0, true, true, false), (128, 160, 0, 0, false, true, true), (160, 128, 0, 0, true, false, true)) | | 80x160 | ((80, 160, 26, 1, false, false, false), (160, 80, 1, 26, true, true, false), (80, 160, 26, 1, false, true, true), (160, 80, 1, 26, true, false, true)) | | 128x128 | ((128, 128, 2, 1, false, false, false), (128, 128, 1, 2, true, true, false), (128, 128, 2, 3, false, true, true), (128, 128, 3, 2, true, false, true)) |

    You may define up to 4 rotations.

  • rotation sets the active display rotation according to the orientation table.

    The default orientation table defines four counterclockwise rotations for 240x320, 240x240, 134x240, 128x160, 80x160, and 128x128 displays with the LCD's ribbon cable at the bottom of the display. The default rotation is Portrait (0 degrees).

    | Index | Rotation | ----- | ------------------------------- | | 0 | Portrait (0 degrees) | | 1 | Landscape (90 degrees) | | 2 | Reverse Portrait (180 degrees) | | 3 | Reverse Landscape (270 degrees) |

  • inversion Sets the display color inversion mode if True and clears the color inversion mode if false.

  • dma_rows Sets the number of the framebuffer rows to transfer to the display in a single DMA transaction. The default value is 16 rows. Larger values may perform better but use more DMA-capable memory from the ESP-IDF heap. On the other hand, using a large value may starve other ESP-IDF functions like WiFi of memory.

  • options Sets driver option flags.

    | Option | Description | | ------------ | -------------------------------------------------------------------------------------------------------- | | s3lcd.WRAP | pixels, lines, polygons, and Hershey text will wrap around the display both horizontally and vertically. | | s3lcd.WRAP_H | pixels, lines, polygons, and Hershey text will wrap around the display horizontally. | | s3lcd.WRAP_V | pixels, lines, polygons, and Hershey text will wrap around the display vertically. |

• deinit()

  Frees the buffer memory and deinitializes the I80_BUF or SPI_BUF object. Call this method before reinitializing the display without performing a hard reset.

• idle_mode(value)

  Set idle mode

  value: True to enable idle mode, False to idle disable idle mode.

• show()

  Update the display from the framebuffer. You must use the show() method to transfer the framebuffer to the display. This method blocks until the display refresh is complete.

• inversion_mode(bool) Sets the display color inversion mode if True, clears the display color inversion mode if False.

• init()

  Must be called to initialize the display.

• clear({ 8_bit_color})

  Fast clear the framebuffer by setting the high and low bytes of the color to the specified value.

  Optional parameters: -- 8_bit_color defaults to 0x00 BLACK

• fill({color, alpha})

  Fill the framebuffer with the specified color, optionally alpha blended with the background. The color defaults to BLACK, and the alpha defaults to 255.

• pixel(x, y {, color, alpha})

  Set the specified pixel to the given color. The color defaults to WHITE, and