uploaded 3 weeks 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.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 | | --- | ----- | | SPI MISO | 2 | | SPI MOSI | 15 | | SPI CLK | 14 | | TFT CS | 16 | | TFT Reset | (not configured) | | TFT DC | 17 | | 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 | | --- | ----- | | SPI MISO | 13 | | SPI MOSI | 10 | | SPI CLK | 11 | | TFT CS | 3 | | TFT Reset | 46 | | TFT DC | 9 | | TFT Backlight | 12 |

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


Supports all targets

License: MIT

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

or download archive


  • ESP-IDF >=4.4.2
  • Examples:


    atanisoft/esp_lcd_ili9488 version: 1.0.7