readme
# 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](https://focuslcds.com/content/ILI9488.pdf) |
## 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](https://components.espressif.com/) as:
```
dependencies:
atanisoft/esp_lcd_ili9488: "~1.0.0"
```
2. Using the git repository directly:
```
dependencies:
esp_lcd_ili9488:
git: https://github.com/atanisoft/esp_lcd_ili9488.git
```
For more information on the usage of the `idf_component.yml` file please refer to [Espressif's documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html).
## 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.
changelog
# 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.
Fixed: https://github.com/atanisoft/esp_lcd_ili9488/issues/1
## 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 `idf.py 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 `idf.py 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](main/lvgl_example_main.c), and the UI demo code is located in [another single file](main/lvgl_demo_ui.c).
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](https://lvgl.io/tools/imageconverter), and will be compiled directly into application binary.
This example is constructed by [IDF component manager](https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/tools/idf-component-manager.html), all the external dependency will be handled by the CMake build system automatically. In this case, it will help download the lvgl from [lvgl](https://components.espressif.com/component/lvgl/lvgl) and esp_lcd_ili9488 from [esp_lcd_ili9488](https://components.espressif.com/components/atanisoft/esp_lcd_ili9488), with the version specified in the [manifest file](main/idf_component.yml).
This example uses the [esp_timer](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/esp_timer.html) to generate the ticks needed by LVGL. For more porting guides, please refer to [LVGL porting doc](https://docs.lvgl.io/master/porting/index.html).
## 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](main/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](main/lvgl_example_main.c).
### Build and Flash
Run `idf.py -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 `idf.py` 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](https://docs.espressif.com/projects/esp-idf/en/latest/get-started/index.html) for full steps to configure and use ESP-IDF to build projects.
### Example Output
```bash
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
```