MIPI RGB Display Driver

Types of Display

This display driver supports displays with 16 bit parallel interfaces, often referred to as “RGB”. Two classes of display fall under this category, the first are those that only have the RGB interface and require no special configuration of the driver chip. The second are those that have both the RGB interface and an SPI interface which is used to configure the driver chip.

Supported boards and driver chips

The driver supports a number of display driver chips, and can be configured for custom displays. As well as support for driver chips, there are also specific configurations for several ESP32 boards with integrated displays. For those boards the predefined configuration will set the correct pins and dimensions for the display.

For custom displays, the driver can be configured with the correct pins and dimensions, and the driver chip can be specified, or a custom init sequence can be provided.

Driver chips

Driver Chip	Typical Dimensions
ST7701S	480x480
RPI	varies

The RPI driver chip represents displays without an SPI interface, so no init sequence is required.

Supported integrated display boards

These boards have completely pre-filled configurations for the display driver, so the only required configuration option is model.

Board	Driver Chip	Manufacturer	Product link
GUITION-4848S040	ST7701s	Guition	https://devices.esphome.io/devices/Guition-ESP32-S3-4848S040
T-PANEL-S3	ST7701s	Lilygo	https://lilygo.cc/products/t-panel-s3
T-RGB-2.1	ST7701s	Lilygo	https://lilygo.cc/products/t-rgb
T-RGB-2.8	ST7701s	Lilygo	https://lilygo.cc/products/t-rgb
SEEED-INDICATOR-D1	ST7701s	Seeed Studio	https://www.seeedstudio.com/SenseCAP-Indicator-D1L-p-5646.html
ESP32-S3-TOUCH-LCD-4.3	RPI	Waveshare	https://www.waveshare.com/esp32-s3-touch-lcd-4.3.htm
ESP32-S3-TOUCH-LCD-7-800X480	RPI	Waveshare	https://www.waveshare.com/esp32-s3-touch-lcd-7.htm
WAVESHARE-4-480x480	RPI	Waveshare	https://www.waveshare.com/esp32-s3-touch-lcd-4.htm

Usage

This component requires an ESP32 (usually an ESP32-S3 because of the number of GPIO pins required) and the use of ESP-IDF. PSRAM is a requirement due to the size of the display buffer.

# Example minimal configuration entry
display:
  - platform: mipi_rgb
    model: WAVESHARE-4-480x480
    id: my_display
    

Configuration variables:

invert_colors (Optional): With this boolean option you can invert the display colors. Note some of the displays have this option set automatically to true and can’t be changed.
rotation (Optional): Rotate the display presentation in software. Choose one of 0° , 90° , 180° , or 270° . This option cannot be used with transform .
transform (Optional): Transform the display presentation using hardware. All defaults are false . This option cannot be used with rotation .
- mirror_x (Optional, boolean): If true, mirror the x-axis.
- mirror_y (Optional, boolean): If true, mirror the y-axis. Note: To rotate the display in hardware by 180 degrees set both mirror_x and mirror_y to true.
update_interval (Optional, Time): The interval to re-draw the screen. Defaults to 5s .
auto_clear_enabled (Optional, boolean): If the display should be cleared before each update. Defaults to true if a lambda or pages are configured, false otherwise.
lambda (Optional, lambda): The lambda to use for rendering the content on the display. See Display Rendering Engine for more information.
pages (Optional, list): Show pages instead of a single lambda. See Display Pages.
id (Optional, ID): Manually specify the ID used for code generation.
color_order (Optional): Should be one of bgr (default) or rgb .
dimensions (Required): Dimensions of the screen, specified either as width x height (e.g 320x240 ) or with separate config keys.
- height (Required, int): Specifies height of display in pixels.
- width (Required, int): Specifies width of display.
- offset_width (Optional, int): Specify an offset for the x-direction of the display, typically used when an LCD is smaller than the maximum supported by the driver chip. Default is 0
- offset_height (Optional, int): Specify an offset for the y-direction of the display. Default is 0.
data_pins (Required): A list of pins used for the databus. Specified in 3 groups.
- red (Required, Pin Schema): Exactly 5 pins for the red databits, listed from least to most significant bit.
- green (Required, Pin Schema): Exactly 6 pins for the green databits, listed from least to most significant bit.
- blue (Required, Pin Schema): Exactly 5 pins for the blue databits, listed from least to most significant bit.
de_pin (Required, Pin Schema): The DE pin.
pclk_pin (Required, Pin Schema): The PCLK pin.
hsync_pin (Required, Pin Schema): The Horizontal sync pin.
vsync_pin (Required, Pin Schema): The Vertical sync pin.
reset_pin (Optional, Pin Schema): The RESET pin.
hsync_pulse_width (Optional, int): The horizontal sync pulse width.
hsync_front_porch (Optional, int): The horizontal front porch length.
hsync_back_porch (Optional, int): The horizontal back porch length.
vsync_pulse_width (Optional, int): The vertical sync pulse width.
vsync_front_porch (Optional, int): The vertical front porch length.
vsync_back_porch (Optional, int): The vertical back porch length.
pclk_frequency (Optional): Set the pixel clock speed. Default is 8MHz.
pclk_inverted (Optional, bool): If the pclk is active negative (default is True)

The horizontal and vertical pulse_width , front_porch and back_porch values are optional, but will likely require changing from the default values for a specific display. Refer to the manufacturer’s sample code for suitable values. These specify timing requirements for the display.

Additional Configuration for non-RPI displays

Displays needing a custom init sequence require an SPI bus to be configured, plus these options:

dc_pin (Optional, Pin Schema): The DC pin.
data_rate (Optional): Set the data rate of the SPI interface to the display. One of 80MHz , 40MHz , 20MHz , 10MHz , 5MHz , 2MHz , 1MHz (default), 200kHz , 75kHz or 1kHz .
spi_mode (Optional): Set the mode for the SPI interface to the display. Default is MODE0 but some displays require MODE3 .
spi_id (Optional, ID): The ID of the SPI interface to use - may be omitted if only one SPI bus is configured.
init_sequence (Optional, A list of byte arrays): Specifies the init sequence for the display. Predefined boards have a default init sequence, which can be overridden. A custom board can specify the init sequence using this variable. RPI displays should provide an empty sequence in which case the SPI bus is not required.

The init_sequence requires a list of elements, one of which may be a single integer selecting a canned init sequence (the default and currently the only sequence is 1), the remainder must be byte arrays providing additional init commands, each consisting of a command byte followed by zero or more data bytes.

A delay may be specified with delay <N>ms

These will be collected and sent to the display via SPI during initialisation. The SPI bus need not be implemented in hardware (i.e. it may use interface: software) and it will be released after initialisation, before the RGB driver is configured. This caters for boards that use the SPI bus pins as RGB pins.

Example configurations

This is an example of a full custom configuration.

display:
  - platform: mipi_rgb
    update_interval: never
    spi_mode: MODE3
    color_order: RGB
    dimensions:
      width: 480
      height: 480
    invert_colors: true
    transform:
      mirror_x: true
      mirror_y: true
    cs_pin:
      pca9554: p_c_a
      number: 4
    reset_pin:
      pca9554: p_c_a
      number: 5
    de_pin: 18
    hsync_pin: 16
    vsync_pin: 17
    pclk_pin: 21
    init_sequence:
      - 1 # select canned init sequence number 1
      - delay 5ms
      - [ 0xE0, 0x1F ]  # Set sunlight readable enhancement
    data_pins:
      red:
        - 4         #r1
        - 3         #r2
        - 2         #r3
        - 1         #r4
        - 0         #r5
      green:
        - 10        #g0
        - 9         #g1
        - 8         #g2
        - 7         #g3
        - 6         #g4
        - 5         #g5
      blue:
        - 15        #b1
        - 14        #b2
        - 13        #b3
        - 12        #b4
        - 11        #b5
    lambda: |-
      it.fill(COLOR_BLACK);
      it.print(0, 0, id(my_font), id(my_red), TextAlign::TOP_LEFT, "Hello World!");