uploaded 1 month ago
esp_lcd driver for ILI9488 displays


esp_lcd driver for ILI9488 displays

This component provides an implementation of the ILI9488 LCD controller using the esp_lcd component APIs.

LCD controller Communication interface Component name Link to datasheet
ILI9488 SPI or Intel 8080 esp_lcd_ili9488 Specification

Note on supported communication interfaces

When using the SPI interface it is required to use 18-bit color depth mode as below:

    const esp_lcd_panel_dev_config_t lcd_config = 
        .bits_per_pixel = 18,

When using the Intel 8080 (Parallel) interface the 16-bit color depth mode should be used.

Display Reset pin

If the display requires the usage of a RESET pin during the initialization process be sure to configure it as below:

    const esp_lcd_panel_dev_config_t lcd_config = 
        .reset_gpio_num = CONFIG_TFT_RESET_PIN,

If the display does not require this pin set this value to GPIO_NUM_NC (-1).

Using this component in your project

This package can be added to your project in two ways:

  1. Using Espressif's component service as:
  atanisoft/esp_lcd_ili9488: "~1.0.0"
  1. Using the git repository directly:

For more information on the usage of the idf_component.yml file please refer to Espressif's documentation.

Supported platforms

At this time testing is limited to ESP32 and ESP32-S3, other ESP32 variants should work but are not tested.

Required sdkconfig entries

This driver converts the color data from 16-bit to 18-bit as part of the draw_bitmap callback. Therefore it is required to set CONFIG_LV_COLOR_DEPTH_16=y in your sdkconfig. In the future other color depths may be supported.


Change log for esp_lcd_ili9488

v1.0.8 - Adds support for portrait / landscape orientation.

Thanks to a contribution from @jacobvc it is possible to configure the display as portrait (default) or landscape.

v1.0.5 - Add 16-bit support for parallel IO interface support

Parallel IO mode (Intel 8080 interface) should use 16-bit color mode instead of being forced into 18-bit color mode that is required for use when the SPI interface is used.

v1.0.4 - License tagging fixes

This release only updates the SPDX license tagging of source files.

v1.0.3 - Bug Fixes and LVGL example update

This release removes (and desupports) a dependency on 32-bit color depth when using LVGL, the color conversion code has only ever supported 16-bit color data but was incorrectly casting the source color data to uint32_t instead of uint16_t.

As a result of the above bug fix the esp_lcd_panel_dev_config_t field bits_per_pixel will be ignored by esp_lcd_new_panel_ili9488 and the ILI9488 will always use the 18-bit color mode.

The LVGL example has been updated as below:

  • Remove unused lvgl_port_update_callback since the example does not include touch support or any screen rotation API calls.
  • Add option for enabling / disabling double buffering with LVGL, default is to use a single buffer.
  • Added missing Kconfig.projbuild entry for TFT_RESET_PIN, added new entry DISPLAY_COLOR_MODE which can be used to toggle between BGR and RGB color mode on the ILI9488 display.
  • Enhanced example to switch from only using lv_spinner_create to instead use lv_meter_create and lv_anim_t to display an animated gauge.
  • Reduced default backlight brightness to 75%.
  • Switched from using esp_register_freertos_tick_hook to esp_timer_create for the tick update handler.
  • Add code to set the background color of the display to black.

v1.0.2 - Bug Fix Release

This release contains a bug fix related to a compilation failure with ESP-IDF v5.0.1 replacing esp_lcd_color_space_t with lcd_color_rgb_endian_t but retaining the original name in esp_lcd_panel_dev_config_t for the value. At this time the library supports both ESP-IDF v4.4.x and v5.x but the new values in lcd_color_rgb_endian_t are not being used as they are compatible with the existing values defined in esp_lcd_color_space_t, once ESP-IDF v5.1.x has become stable and legacy enums are removed this library will be updated accordingly.


v1.0.1 - No changes

v1.0.0 - Initial release

This release is the first revision of this component and includes basic support for ILI9488 displays including the 18-bit color depth conversion which is required for SPI interface displays.

readme of lvgl example

LVGL Example using ILI9488 display

This is a very basic example using LVGL and an ILI9488 SPI display.

Default pin assignments

For the ESP32 pins are as follows:

pin usage
TFT Reset (not configured)
TFT Backlight 18

On the ESP32 only the TFT pins can be reconfiguring by using menuconfig.

For the ESP32-S3 pins are as follows:

pin usage
TFT Reset 46
TFT Backlight 12

On the ESP32-S3 all pins can be reconfigured by using menuconfig.

readme of lvgl_for_i8080 example

Supported Targets ESP32 ESP32-S2 ESP32-S3

LVGL porting example

LVGL is an open-source graphics library for creating modern GUIs. It has plenty of built-in graphical elements with low memory footprint, which is friendly for embedded GUI applications.

This example can be taken as a skeleton of porting the LVGL library onto the esp_lcd driver layer. Note that, this example only focuses on the display interface, regardless of the input device driver.

The whole porting code is located in this main file, and the UI demo code is located in another single file.

The UI will display two images (one Espressif logo and another Espressif text), which have been converted into C arrays by the online converting tool, and will be compiled directly into application binary.

This example is constructed by IDF component manager, all the external dependency will be handled by the CMake build system automatically. In this case, it will help download the lvgl from lvgl and esp_lcd_ili9488 from esp_lcd_ili9488, with the version specified in the manifest file.

This example uses the esp_timer to generate the ticks needed by LVGL. For more porting guides, please refer to LVGL porting doc.

How to use the example

Hardware Required

  • An ESP development board
  • An Intel 8080 interfaced (so called MCU interface or parallel interface) LCD
  • An USB cable for power supply and programming

Hardware Connection

The connection between ESP Board and the LCD is as follows:

   ESP3233 Board                  LCD Screen
┌─────────────┐              ┌────────────────┐
│             │              │                │
│         3V3 ├─────────────►│ VCC            │
│             │              │                │
│         GND ├──────────────┤ GND            │
│             │              │                │
│  DATA[0..7] │◄────────────►│ DATA[0..7]     │
│             │              │                │
│        IO12 ├─────────────►│ PCLK           │
│             │              │                │
│        IO10 ├─────────────►│ CS             │
│             │              │                │
│        IO14 ├─────────────►│ D/C            │
│             │              │                │
│         IO9 ├─────────────►│ RST            │
│             │              │                │
│        IO46 ├─────────────►│ BCKL           │
│             │              │                │
└─────────────┘              └────────────────┘

The GPIO number used by this example can be changed in lvgl_example_main.c. Especially, please pay attention to the level used to turn on the LCD backlight, some LCD module needs a low level to turn it on, while others take a high level. You can change the backlight level macro EXAMPLE_LCD_BK_LIGHT_ON_LEVEL in lvgl_example_main.c.

Build and Flash

Run -p PORT build flash monitor to build, flash and monitor the project. A fancy animation will show up on the LCD as expected.

The first time you run for the example will cost extra time as the build system needs to address the component dependencies and downloads the missing components from registry into managed_components folder.

(To exit the serial monitor, type Ctrl-].)

See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.

Example Output

I (321) cpu_start: Starting scheduler on PRO CPU.
I (0) cpu_start: Starting scheduler on APP CPU.
I (341) example: Turn off LCD backlight
I (341) gpio: GPIO[46]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
I (351) example: Initialize Intel 8080 bus
I (351) example: Install LCD driver of ili9488
I (361) gpio: GPIO[9]| InputEn: 0| OutputEn: 1| OpenDrain: 0| Pullup: 0| Pulldown: 0| Intr:0 
I (371) ili9488: Configuring for RGB color order
I (371) ili9488: new ili9488 panel @0x3fce9e38
I (381) ili9488: Setting GPIO:9 to 0
I (391) ili9488: Setting GPIO:9 to 1
I (401) ili9488: Initializing ILI9488
I (601) ili9488: Initialization complete
I (601) example: Turn on LCD backlight
I (601) example: Initialize LVGL library
I (601) example: Register display driver to LVGL
I (611) example: Install LVGL tick timer
I (611) example: Display LVGL animation


Supports all targets

License: MIT

To add this component to your project, run: add-dependency "atanisoft/esp_lcd_ili9488^1.0.9"

or download archive


  • ESP-IDF >=4.4.2
  • Examples:


    more details


    • Downloaded in total
      Downloaded in total 222 times
    • Downloaded this version
      This version: 51 times


    atanisoft/esp_lcd_ili9488 version: 1.0.9 |