ESP Display Panel

中文版本

ESP32_Display_Panel is an Arduino library designed for ESP SoCs to drive display panels and facilitate rapid GUI development. Users can develop directly for a variety of supported development boards or create custom ones through simple adaptation. Additionally, ESP32_Display_Panel is compatible with various LCD and touch drivers, allowing users to develop using standalone drivers as needed.

ESP32_Display_Panel encapsulates various components from the Espressif Components Registry, requiring development based on arduino-esp32, and can be directly downloaded from the Arduino IDE.

ESP Display Panel

Overview

The functional block diagram of ESP32_Display_Panel is as follows, mainly comprising the following features:

Supports a variety of official Espressif development boards and third-party boards.
Supports adaptation for custom development boards.
Supports the use of standalone device drivers.
Supports various types of device drivers, including interface buses, LCDs, touch screens, and backlight control.
Supports dynamic configuration of drivers, such as enabling debug logs.

Supported Development Boards and Drivers

Development Boards

Below is a list of supported development boards:

Manufacturer	Board Model
Espressif	ESP32-C3-LCDkit, ESP32-S3-Box, ESP32-S3-Box-3, ESP32-S3-Box-3(beta), ESP32-S3-Box-Lite, ESP32-S3-EYE, ESP32-S3-Korvo-2, ESP32-S3-LCD-EV-Board, ESP32-S3-LCD-EV-Board-2, ESP32-S3-USB-OTG
M5Stack	M5STACK-M5CORE2, M5STACK-M5DIAL, M5STACK-M5CORES3
Jingcai	ESP32-4848S040C_I_Y_3

Developers and manufacturers are welcomed to contribute PRs to add more development boards. For detailed instructions, please refer to the Board Development Guide.

LCD Controllers

Below is a list of supported LCD controllers:

Manufacturer	Model
GalaxyCore	GC9A01, GC9B71, GC9503
Ilitek	ILI9341
NewVision	NV3022B
Sitronix	ST7262, ST7701, ST7789, ST7796, ST77916, ST77922

Touch Controllers

Below is a list of supported touch controllers:

Manufacturer	Model
Hynitron	CST816S
FocalTech	FT5x06
GOODiX	GT911, GT1151
Sitronix	ST7123
Parade	TT21100
Xptek	XPT2046

Dependencies and Versions

Dependency	Version
arduino-esp32	>= v3.0.0-alpha3
ESP32_IO_Expander	>= 0.0.1 && < 0.1.0

How to Use

For installation of the ESP32_Display_Panel library, refer to How to Install ESP32_Display_Panel in Arduino IDE.

Configuration Instructions

Below are detailed instructions on how to configure ESP32_Display_Panel, mainly including Configuring Drivers, Using Supported Development Boards, and Using Custom Development Boards. These are all optional operations and are configured through specified header files. Users can choose to use them according to their needs, with the following characteristics:

The path sequence for ESP32_Display_Panel to search for configuration files is: Current Project Directory > Arduino Library Directory > ESP32_Display_Panel Directory.
All examples in ESP32_Display_Panel include their required configuration files by default, which users can directly modify macro definitions.
For projects without configuration files, users can copy them from the root directory or examples of ESP32_Display_Panel to their own projects.
If multiple projects need to use the same configuration, users can place the configuration files in the Arduino Library Directory, so that all projects can share the same configuration.

Notes:

The same directory can simultaneously contain both ESP_Panel_Board_Supported.h and ESP_Panel_Board_Custom.h configuration files, but they cannot be enabled at the same time, meaning ESP_PANEL_USE_SUPPORTED_BOARD and ESP_PANEL_USE_CUSTOM_BOARD can only have one set to 1.
If neither of the above two configuration files is enabled, users cannot use the ESP_Panel driver and can only use other standalone device drivers, such as ESP_PanelBus, ESP_PanelLcd, etc.

Configuring Drivers

ESP32_Display_Panel configures driver functionality and parameters based on the ESP_Panel_Conf.h file. Users can update the behavior or default parameters of the driver by modifying macro definitions in this file. For example, to enable debug log output, here is a snippet of the modified ESP_Panel_Conf.h file:

...
/* Set to 1 if print log message for debug */
#define ESP_PANEL_ENABLE_LOG                (1)         // 0/1
...

Using Supported Development Boards

ESP32_Display_Panel configures ESP_Panel as the driver for the target development board based on the ESP_Panel_Board_Supported.h file. Users can select supported development boards by modifying macro definitions in this file. For example, to use the ESP32-S3-Box-3 development board, follow these steps:

Set the ESP_PANEL_USE_SUPPORTED_BOARD macro definition in the ESP_Panel_Board_Supported.h file to 1.
Uncomment the corresponding macro definition for the target development board model.

Here is a snippet of the modified ESP_Panel_Board_Supported.h file:

...
/* Set to 1 if using a supported board */
#define ESP_PANEL_USE_SUPPORTED_BOARD       (1)         // 0/1

#if ESP_PANEL_USE_SUPPORTED_BOARD
...
// #define BOARD_ESP32_C3_LCDKIT
// #define BOARD_ESP32_S3_BOX
#define BOARD_ESP32_S3_BOX_3
// #define BOARD_ESP32_S3_BOX_3_BETA
...
#endif /* ESP_PANEL_USE_SUPPORTED_BOARD */

Using Custom Development Boards

ESP32_Display_Panel configures ESP_Panel as the driver for custom development boards based on the ESP_Panel_Board_Custom.h file. Users need to modify this file according to the actual parameters of the custom development board. For example, to use a custom development board with a 480x480 RGB ST7701 LCD + I2C GT911 Touch, follow these steps:

Set the ESP_PANEL_USE_CUSTOM_BOARD macro definition in the ESP_Panel_Board_Custom.h file to 1.
Set the LCD-related macro definitions: a. Set ESP_PANEL_USE_LCD to 1. b. Set ESP_PANEL_LCD_WIDTH and ESP_PANEL_LCD_HEIGHT to 480. c. Set ESP_PANEL_LCD_BUS_TYPE to ESP_PANEL_BUS_TYPE_RGB. d. Set LCD signal pins and other parameters below ESP_PANEL_LCD_BUS_TYPE == ESP_PANEL_BUS_TYPE_RGB. e. Uncomment and modify the ESP_PANEL_LCD_VENDOR_INIT_CMD macro definition according to the initialization command parameters provided by the screen vendor. f. Modify other LCD configurations as needed.
Set the Touch-related macro definitions: a. Set ESP_PANEL_USE_TOUCH to 1. b. Set Touch signal pins and other parameters below ESP_PANEL_TOUCH_BUS_TYPE == ESP_PANEL_BUS_TYPE_I2C. c. Modify other Touch configurations as needed.
Enable other driver macro definitions as needed, such as ESP_PANEL_USE_BACKLIGHT, ESP_PANEL_USE_EXPANDER, etc.

Here is a snippet of the modified ESP_Panel_Board_Custom.h file:

...
/* Set to 1 if using a custom board */
#define ESP_PANEL_USE_CUSTOM_BOARD  (1)         // 0/1

/* Set to 1 when using an LCD panel */
#define ESP_PANEL_USE_LCD           (1)     // 0/1

#if ESP_PANEL_USE_LCD
/**
 * LCD Controller Name
 */
#define ESP_PANEL_LCD_NAME          ST7701

/* LCD resolution in pixels */
#define ESP_PANEL_LCD_WIDTH         (480)
#define ESP_PANEL_LCD_HEIGHT        (480)
...
/**
 * LCD Bus Type.
 */
#define ESP_PANEL_LCD_BUS_TYPE      (ESP_PANEL_BUS_TYPE_RGB)
/**
 * LCD Bus Parameters.
 *
 * Please refer to https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-reference/peripherals/lcd.html and
 * https://docs.espressif.com/projects/esp-iot-solution/en/latest/display/lcd/index.html for more details.
 *
 */
#if ESP_PANEL_LCD_BUS_TYPE == ESP_PANEL_BUS_TYPE_RGB
...
#endif /* ESP_PANEL_LCD_BUS_TYPE */
...
/**
 * LCD Vendor Initialization Commands.
 *
 * Vendor specific initialization can be different between manufacturers, should consult the LCD supplier for
 * initialization sequence code. Please uncomment and change the following macro definitions. Otherwise, the LCD driver
 * will use the default initialization sequence code.
 *
 * There are two formats for the sequence code:
 *   1. Raw data: {command, (uint8_t []){ data0, data1, ... }, data_size, delay_ms}
 *   2. Formater: ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(delay_ms, command, { data0, data1, ... }) and
 *                ESP_PANEL_LCD_CMD_WITH_NONE_PARAM(delay_ms, command)
 */
#define ESP_PANEL_LCD_VENDOR_INIT_CMD() \
    { \
        ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(0, 0xFF, {0x77, 0x01, 0x00, 0x00, 0x10}), \
        ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(0, 0xC0, {0x3B, 0x00}), \
        ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(0, 0xC1, {0x0D, 0x02}), \
        ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(0, 0xC2, {0x31, 0x05}), \
        ESP_PANEL_LCD_CMD_WITH_8BIT_PARAM(0, 0xCD, {0x00}), \
        ...
        ESP_PANEL_LCD_CMD_WITH_NONE_PARAM(120, 0x11), \
    }
...
#endif /* ESP_PANEL_USE_LCD */

/* Set to 1 when using a touch panel */
#define ESP_PANEL_USE_TOUCH         (1)         // 0/1
#if ESP_PANEL_USE_TOUCH
/**
 * Touch controller name
 */
#define ESP_PANEL_TOUCH_NAME        GT911
...
/**
 * Touch panel bus type
 */
#define ESP_PANEL_TOUCH_BUS_TYPE    (ESP_PANEL_BUS_TYPE_I2C)
/* Touch panel bus parameters */
#if ESP_PANEL_TOUCH_BUS_TYPE == ESP_PANEL_BUS_TYPE_I2C
...
#endif /* ESP_PANEL_TOUCH_BUS_TYPE */
...
#endif /* ESP_PANEL_USE_TOUCH */
...
#define ESP_PANEL_USE_BACKLIGHT     (1)         // 0/1
#if ESP_PANEL_USE_BACKLIGHT
...
#endif /* ESP_PANEL_USE_BACKLIGHT */
...
#endif /* ESP_PANEL_USE_CUSTOM_BOARD */

Usage Examples

The following are some examples of using ESP32_Display_Panel on different development platforms.

Arduino IDE

You can access them in the Arduino IDE by navigating to File > Examples > ESP32_Display_Panel. If you cannot find the ESP32_Display_Panel option, please check if the library has been installed correctly and ensure that an ESP development board is selected.

LCD

The following examples demonstrate how to develop different interface and model LCDs using standalone drivers and test them by displaying color bars:

Touch

The following example demonstrates how to develop touch screens of different interfaces and models using standalone drivers and test them by printing touch point coordinates:

Panel

The following example demonstrates how to develop built-in or custom development boards using the ESP_Panel driver:

Panel Test: This example tests by displaying color bars and printing touch point coordinates.

LVGL v8

For configuring LVGL (v8.3.x), please refer to here for more detailed information.

Porting: This example demonstrates how to port LVGL (v8.3.x). And for RGB LCD, it can enable the avoid tearing fucntion.
Rotation: This example demonstrates how to use LVGL to rotate the display.

SquareLine

To port the SquareLine project (v1.3.x), please refer to here for more detailed information.

Porting: This example demonstrates how to port the SquareLine project.
WiFiClock: This example implements a simple Wi-Fi clock and can display weather information.

PlatformIO

PlatformIO: This example demonstrates how to use ESP32_Display_Panel in PlatformIO. By default, it is suitable for the ESP32-S3-LCD-EV-Board and ESP32-S3-LCD-EV-Board-2 development boards. Users need to modify the boards/ESP-LCD.json file according to the actual situation.

Other Relevant Instructions

Configuring Supported Development Boards

For details on how to configure the supported development boards in the Arduino IDE, see Board_Instructions.md.

Configuring LVGL

The functionality and parameters of LVGL can be configured by editing the lv_conf.h file, where users can modify macro definitions to update the behavior or default parameters of the driver. Here are some features for configuring LVGL:

When using arduino-esp32 v3.x.x version, LVGL will search for the configuration file in the following order: current project directory > Arduino library directory. If the configuration file is not found, a compilation error indicating the absence of the configuration file will be prompted. Therefore, users need to ensure that at least one directory contains the lv_conf.h file.
If multiple projects need to use the same configuration, users can place the configuration file in the Arduino library directory, so that all projects can share the same configuration.

Below are detailed steps for sharing the same LVGL configuration:

Navigate to the Arduino library directory.
Enter the lvgl folder, copy the lv_conf_template.h file, and place the copy at the same level as the lvgl folder. Then, rename the copied file to lv_conf.h.

Finally, the layout of the Arduino library folder should look like this:

Arduino
   |-libraries
       |-lv_conf.h
       |-lvgl
       |-other_lib_1
       |-other_lib_2

Open the lv_conf.h file, and change the first #if 0 to #if 1 to enable the contents of the file.

Set other configurations according to requirements. Here are some examples of common configuration options for LVGL v8:

#define LV_COLOR_DEPTH          16  // Typically use 16-bit color depth (RGB565),
                                   // but can also set it to `32` to support 24-bit color depth (RGB888)
#define LV_COLOR_16_SWAP        0   // If using SPI/QSPI LCD (e.g., ESP32-C3-LCDkit), set this to `1`
#define LV_COLOR_SCREEN_TRANSP  1
#define LV_MEM_CUSTOM           1
#define LV_MEMCPY_MEMSET_STD    1
#define LV_TICK_CUSTOM          1
#define LV_ATTRIBUTE_FAST_MEM   IRAM_ATTR
                                  // Get higher performance but use more SRAM
#define LV_FONT_MONTSERRAT_N    1  // Enable all internal fonts needed (`N` should be replaced with font size)

For more information, please refer to the LVGL official documentation.

Porting SquareLine Project

SquareLine Studio (v1.3.x) allows for the rapid design of beautiful UIs through visual editing. If you want to use UI source files exported from SquareLine in the Arduino IDE, you can follow these steps for porting:

First, create a new project in SquareLine Studio. Go to Create -> Arduino, select Arduino with TFT-eSPI as the project template, then configure the LCD properties for the target development board in the PROJECT SETTINGS section, such as Resolution and Color depth. Finally, click the Create button to create the project.
For existing projects, you can also click on File -> Project Settings in the navigation bar to enter the project settings. Then, in the BOARD PROPERTIES section, configure Board Group as Arduino and Board as Arduino with TFT-eSPI. Additionally, configure the LCD properties for the target development board in the DISPLAY PROPERTIES section. Finally, click the Save button to save the project settings.
Once the UI design is complete and the export path is configured, click on Export -> Create Template Project and Export UI Files buttons in the menu bar to export the project and UI source files. The layout of the project directory will be as follows:
```
Project
    |-libraries
        |-lv_conf.h
        |-lvgl
        |-readme.txt
        |-TFT_eSPI
        |-ui
    |-README.md
    |-ui
```
Copy the lv_conf.h, lvgl, and ui folders from the libraries folder in the project directory to the Arduino library directory. If you need to use a locally installed lvgl, skip copying lvgl and lv_conf.h, then refer to the steps in the LVGL Configuration section to configure LVGL. The layout of the Arduino library folder will be as follows:
```
Arduino
    |-libraries
        |-ESP32_Display_Panel
        |-ESP_Panel_Conf.h (optional)
        |-lv_conf.h (optional)
        |-lvgl
        |-ui
        |-other_lib_1
        |-other_lib_2
```

FAQ

Where is the directory for Arduino libraries?

You can find and modify the directory path for Arduino libraries by selecting File > Preferences > Settings > Sketchbook location from the menu bar in the Arduino IDE.

How to Install ESP32_Display_Panel in Arduino IDE?

If you want to install online, navigate to Sketch > Include Library > Manage Libraries... in the Arduino IDE, then search for ESP32_Display_Panel and click the Install button to install it.
If you want to install manually, download the required version of the .zip file from ESP32_Display_Panel, then navigate to Sketch > Include Library > Add .ZIP Library... in the Arduino IDE, select the downloaded .zip file, and click Open to install it.
You can also refer to the guides on library installation in the Arduino IDE v1.x.x or Arduino IDE v2.x.x documentation.

Where are the installation directory for arduino-esp32 and the SDK located?

The default installation path for arduino-esp32 depends on your operating system:

Windows: C:\Users\<user name>\AppData\Local\Arduino15\packages\esp32
Linux: ~/.arduino15/packages/esp32

The SDK for arduino-esp32 v3.x.x version is located in the tools/esp32-arduino-libs/idf-release_x directory within the default installation path.

How to fix screen drift issue when driving RGB LCD with ESP32-S3?

When encountering screen drift issue when driving RGB LCD with ESP32-S3, you can follow these steps to resolve them:

Refer to Documentation: Understand the issue description in detail, you can refer to this document.
Enable Bounce Buffer + XIP on PSRAM Feature: To resolve the issue, it's recommended to enable the Bounce Buffer + XIP on PSRAM feature. Follow these steps:
- Step 1: Download the "high_perf" version of the SDK from arduino-esp32-sdk and replace it in the installation directory of arduino-esp32.
- Step 2: If you're using supported development boards, usually there's no need to modify the code as they set ESP_PANEL_LCD_RGB_BOUNCE_BUF_SIZE to (ESP_PANEL_LCD_WIDTH * 10) by default. If the issue persists, refer to the example code below to increase the size of the Bounce Buffer.
- Step 3: If you're using a custom board, confirm in the ESP_Panel_Board_Custom.h file whether ESP_PANEL_LCD_RGB_BOUNCE_BUF_SIZE is set to non-zero. If the issue persists, increase the size of the Bounce Buffer.
- Step 4: If you're using an independent driver, refer to the example code below to set the size of the Bounce Buffer.

Example Code: The following example code demonstrates how to modify the size of the Bounce Buffer using ESP_Panel driver or independent driver:

Example 1: Modify the Bounce Buffer size using the ESP_Panel driver:

...
ESP_Panel *panel = new ESP_Panel();
panel->init();
// Start
ESP_PanelBus_RGB *rgb_bus = static_cast<ESP_PanelBus_RGB *>(panel->getLcd()->getBus());
// The size of the bounce buffer must satisfy `width_of_lcd * height_of_lcd = size_of_buffer * N`, where N is an even number.
rgb_bus->configRgbBounceBufferSize((ESP_PANEL_LCD_WIDTH * 20));
// End
panel->begin();
...

Example 2: Modify the Bounce Buffer size using an independent driver:

...
ESP_PanelBus_RGB *lcd_bus = new ESP_PanelBus_RGB(...);
// Start
// The size of the bounce buffer must satisfy `width_of_lcd * height_of_lcd = size_of_buffer * N`, where N is an even number.
lcd_bus->configRgbBounceBufferSize(EXAMPLE_LCD_WIDTH * 10);
// End
lcd_bus->begin();
...

How to Use ESP32_Display_Panel on PlatformIO?

You can refer to the example PlatformIO to use the ESP32_Display_Panel library in PlatformIO. By default, it is suitable for the ESP32-S3-LCD-EV-Board and ESP32-S3-LCD-EV-Board-2 development boards. You need to modify the boards/ESP-LCD.json file according to the actual situation.

esp-arduino-libs / ESP32_Display_Panel

readme