LittlevGL project for ESP32
Get started
Install the ESP32 SDK
http://esp-idf.readthedocs.io/en/latest/
Note:
This project is compatible with both the ESP-IDF 3.X branch and the 4.0 branch. For the 4.0 branch, you can use either make or CMake, but CMake is recommended. Instructions here are given for the latest toolchain using idf.py
(which invokes CMake), but it is easy to translate to make. For example instead of running idf.py menuconfig
, just run make menuconfig
.
Build this repository standalone and run the demo.
Try this first to make sure your hardware is supported, wired and configured properly.
-
Get this project:
git clone --recurse-submodules https://github.com/littlevgl/esp32_ili9341.git
-
From its root run
idf.py menuconfig
-
Select your display kit or board and other options - see config options
-
idf.py build
-
idf.py -p (YOUR PORT) flash
(with make this is justmake flash
- in 3.x PORT is configured inmenuconfig
)
Install this project as a library submodule in your own project
It is recommended to install this repo as a submodule in your IDF project's git repo. The configuration system has been designed so that you do not need to copy or edit any files in this repo. By keeping your submodule directory clean you can ensure reproducible builds and easy updates from this upstream repository.
From your project root:
mkdir -p externals
git submodule add https://github.com/littlevgl/esp32_ili9341.git externals/esp32_ili9341
git submodule update --init --recursive
- Edit your CMake or Makefile to add this repo's components folder to the IDF components path.
CMake
The examples below are taken from the ESP-IDF blink example which you can copy and use as the basis for your own project. The project root CMakeLists.txt file needs one line added, just before the project to add the extra components directory to the path like this:
#CMakeLists.txt
cmake_minimum_required(VERSION 3.5)
include($ENV{IDF_PATH}/tools/cmake/project.cmake)
set(EXTRA_COMPONENT_DIRS externals/esp32_ili9341/components)
project(blink)
In the CMakeLists.txt file for your /main
or for the component(s) using LVGL you need to add REQUIRES directives for this project's driver and lvgl itself to the idf_component_register
function e.g.
#main/CMakeLists.txt
idf_component_register(
SRCS "blink.c"
INCLUDE_DIRS "."
REQUIRES lvgl_ili9341 lvgl
)
Makefile
If you are using make, you only need to add the EXTRA_COMPONENT_DIRS in the root Makefile of your project:
PROJECT_NAME := blink
EXTRA_COMPONENT_DIRS := externals/esp32_ili9341/components
include $(IDF_PATH)/make/project.mk
Configuration options
There are a number of configuration options available, all accessed through idf.py menuconfig
-> Components -> LittlevGL (LVGL).
Options include:
- Display resolution - set the height and width of the display
- Touch controller present
- Invert display - if text and objects are backwards, you can enable this
- Enable backlight control via GPIO (vs hardwiring on)
- Backlight active high or low - some displays expect a high (1) signal to enable backlight, others expect (low) (default) - if your backlight doesn't come on try switching this
Assign the correct pinout depending on your ESP32 dev board
There are several development boards based on the ESP32 chip, make sure you assign the correct pin numbers to the signals that interface with the TFT display board. Its recommended to use a predefined configuration below, but you can also set individual pins for both display controller and touch controller.
Predefined Display Configurations
For development kits that come with a display already attached, all the correct settings are already known and can be selected in menuconfig
from the first option "Select predefined display configuration." Once selected all the other options will be defaulted and won't appear in the menu.
Boards we currently have defined this way are:
ESP-Wrover-Kit v4.1
This board comes with an embedded TFT screen with the ILI9341 display driver and it doesn't have touch screen. The screen size is 320 x 240 px.
M5Stack
This board comes with an embedded TFT screen with the ILI9341 display driver and it doesn't have touch screen. The screen size is 240 x 320px.
Predefined Board Pinouts
When wiring the display and touchpad (if applicable) it is best to use the board's designated HSPI and VSPI pins to take advantage of the hardware SPI support. Several board configurations are available; select the appropriate board in the "Select predefined board pinouts" menu in menuconfig
and then wire the display and touchpad accordingly.
ESP32 Dev Board with 38 GPIOs
ILI9341 - HSPI
MOSI | CLK | CS | DC | RST | BCKL |
---|---|---|---|---|---|
13 | 14 | 5 | 19 | 18 | 23 |
XPT2046 - VSPI
MOSI | MISO | CLK | CS | IRQ |
---|---|---|---|---|
32 | 35 | 26 | 33 | 25 |
ESP32 DevKit v1 with 30 GPIOS
There is another development kit with only 30 GPIOs available:
ILI9341
For ILI9341 HSPI is used, modify the pin configuration in components/drv/disp_spi.h
to:
ILI9341 - HSPI
MOSI | CLK | CS | DC | RST | BCKL |
---|---|---|---|---|---|
13 | 14 | 15 | 2 | 4 | 21 |
XPT2046 - VSPI
MOSI | MISO | CLK | CS | IRQ |
---|---|---|---|---|
23 | 19 | 18 | 5 | 25 |
ESP32 DevKit v4 with 38 GPIOS
See this pdf for further information: https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_en.pdf
ILI9341 - HSPI
MOSI | CLK | CS | DC | RST | BCKL |
---|---|---|---|---|---|
13 | 14 | 15 | 17 | 25 | 26 |
XPT2046 - VSPI
MOSI | MISO | CLK | CS | IRQ |
---|---|---|---|---|
23 | 19 | 18 | 5 | 27 |
Other Boards
Of course, all the individual pins can be configured in menuconfig
if the available prefines don't match your board or project requirements. By default the prefined options are disabled and pin settings for the 30 pin dev board are defaulted.