1=============================
2Espressif (ESP32 Chip Series)
3=============================
4
5LVGL can be used and configured as standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component.
6
7If you are new to ESP-IDF, follow the instructions in the `ESP-IDF Programming guide <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/get-started/index.html>`__ to install and set up ESP-IDF on your machine.
8
9
10LVGL Demo Projects for ESP32
11----------------------------
12
13For a quick start with LVGL and ESP32, the following pre-configured demo projects are available for specific development boards:
14
15-  `ESP-BOX-3 <https://github.com/lvgl/lv_port_espressif_esp-box-3>`__
16-  `ESP32-S3-LCD-EV-BOARD <https://github.com/lvgl/lv_port_espressif_esp32-s3-lcd-ev-board>`__
17-  `M5Stack-CoreS3 <https://github.com/lvgl/lv_port_espressif_M5Stack_CoreS3>`__
18
19Refer to the README.md files in these repositories for build and flash instructions.
20
21These demo projects use Espressif's Board Support Packages (BSPs). Additional BSPs and examples are available in the `esp-bsp <https://github.com/espressif/esp-bsp>`__ repository.
22
23
24Using LVGL in Your ESP-IDF Project
25----------------------------------
26
27The simplest way to integrate LVGL into your ESP-IDF project is via the `esp_lvgl_port <https://components.espressif.com/components/espressif/esp_lvgl_port>`__ component. This component, used in the demo projects mentioned above, provides helper functions for easy installation of LVGL and display drivers. Moreover, it can add support for touch, rotary encoders, button or USB HID inputs. It simplifies power savings, screen rotation and other platform specific nuances.
28
29The esp_lvgl_port supports LVGL versions 8 and 9 and is compatible with ESP-IDF v4.4 and above. To add it to your project, use the following command:
30
31.. code:: sh
32
33   idf.py add-dependency "espressif/esp_lvgl_port^2.3.0"
34
35By default, esp_lvgl_port depends on the latest stable version of LVGL, so no additional steps are needed for new projects. If a specific LVGL version is required, specify this in your project to avoid automatic updates. LVGL can also be used without esp_lvgl_port, as described below.
36
37Obtaining LVGL
38~~~~~~~~~~~~~~
39
40LVGL is distributed through `ESP Registry <https://components.espressif.com/>`__, where all LVGL releases are uploaded.
41In case you do not want to use esp_lvgl_port, you can add `LVGL component <https://components.espressif.com/component/lvgl/lvgl>`__ into your project with following command:
42
43.. code-block:: sh
44
45   idf.py add-dependency "lvgl/lvgl^9.*"
46
47Adjust the ``^9.*`` part to match your LVGL version requirement. More information on version specifications can be found in the `IDF Component Manager documentation <https://docs.espressif.com/projects/idf-component-manager/en/latest/reference/versioning.html#range-specifications>`__. During the next build, the LVGL component will be fetched from the component registry and added to the project.
48
49**Advanced usage: Use LVGL as local component**
50
51For LVGL development and testing, it may be useful to use LVGL as a local component instead of from the ESP Registry, which offers only released versions and does not allow local modifications. To do this, clone LVGL to your project with the following command:
52
53.. code-block:: sh
54
55   git submodule add https://github.com/lvgl/lvgl.git components/lvgl
56
57.. note::
58
59   All components from ``${project_dir}/components`` are automatically added to build.
60
61Configuration
62~~~~~~~~~~~~~
63
64To configure LVGL, launch the configuration menu with ``idf.py menuconfig`` in your project root directory. Navigate to ``Component config`` and then ``LVGL configuration``.
65
66
67Support for Display and Touch Drivers
68-------------------------------------
69
70For successful LVGL project you will need a display driver and optionally a touch driver. Espressif provides these drivers that are built on its `esp_lcd <https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-reference/peripherals/lcd/index.html>`__ component.
71
72-  esp_lcd natively supports for some `basic displays <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd/src>`__
73-  Other displays are maintained in `esp-bsp repository <https://github.com/espressif/esp-bsp/tree/master/components/lcd>`__ and are uploaded to ESP Registry
74-  Touch drivers are maintained in `esp-bsp repository <https://github.com/espressif/esp-bsp/tree/master/components/lcd_touch>`__ and are uploaded to ESP Registry
75
76These components share a common public API, making it easy to migrate your projects across different display and touch drivers.
77
78To add a display or touch driver to your project, use a command like:
79
80.. code-block:: sh
81
82   idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0"
83
84Using the File System under ESP-IDF
85~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86
87ESP-IDF uses the standard C file operation functions (``fopen``, ``fread``) in all its storage related APIs.
88This allows seamless interoperability with LVGL when enabling the :c:macro:`LV_USE_FS_STDIO` configuration.
89The process is described in details below, using ``SPIFFS`` as demonstration.
90
91- **Decide what storage system you want to use**
92
93   ESP-IDF has many, ready-to-use examples like
94   `SPIFFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/spiffsgen>`__
95   ,
96   `SD Card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdspi>`__
97   and
98   `LittleFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/littlefs>`__
99   .
100
101- **Re-configure your own project**
102
103   The example project should be examined for details, but in general the changes involve:
104
105   - Enabling LVGL's STDIO file system in the configuration
106
107      You can use ``menuconfig``:
108
109         - ``Component config → LVGL configuration → 3rd Party Libraries``: enable ``File system on top of stdio API``
110         - Then select ``Set an upper cased letter on which the drive will accessible`` and set it to ``65`` (ASCII **A**)
111         - You can also set ``Default driver letter`` to 65 to skip the prefix in file paths.
112
113   - Modifying the partition table
114
115      The exact configuration depends on your flash size and existing partitions,
116      but the new final result should look something like this:
117
118      .. csv-table:: Partition Table
119
120         nvs,      data, nvs,     0x9000,  0x6000
121         phy_init, data, phy,     0xf000,  0x1000
122         factory,  app,  factory, 0x10000, 1400k
123         storage,  data, spiffs,         ,  400k
124
125
126      .. note::
127
128         If you are not using a custom ``partition.csv`` yet, it can be added
129         via ``menuconfig`` (``Partition Table → Partition Table → Custom partition table CSV``).
130
131   - Apply changes to the build system
132
133      Some ESP file systems provide automatic generation from a host folder using CMake. The proper line(s) must be copied to ``main/CMakeLists.txt``
134
135      .. note::
136
137         ``LittleFS`` has extra dependencies that should be added to ``main/idf_component.yml``
138
139- **Prepare the image files**
140
141   LVGL's ``LVGLImage.py`` Python tool can be used to convert images to binary pixel map files.
142   It supports various formats and compression.
143
144   Meanwhile 3rd party libraries
145   (like :ref:`LodePNG<lodepng_rst>` and :ref:`Tiny JPEG<tjpgd>`)
146   allow using image files without conversion.
147
148   After preparing the files, they should be moved to the target device:
149
150   - If properly activated a **SPIFFS** file system based on the ``spiffs_image`` folder should be automatically generated and later flashed to the target
151   - Similar mechanism for **LittleFS** uses the ``flash_data`` folder, but it's only available for Linux hosts
152   - For the **SD Card**, a traditional file browser can be used
153
154- **Invoke proper API calls in the application code**
155
156   The core functionality requires only a few lines. The following example draws the image as well.
157
158   .. code:: c
159
160      #include "esp_spiffs.h"
161
162      void lv_example_image_from_esp_fs(void) {
163
164         esp_vfs_spiffs_conf_t conf = {
165            .base_path = "/spiffs",
166            .partition_label = NULL,
167            .max_files = 5,
168            .format_if_mount_failed = false
169         };
170
171         esp_err_t ret = esp_vfs_spiffs_register(&conf);
172
173         if (ret != ESP_OK) {
174            ESP_LOGE(TAG, "Failed to register SPIFF filesystem");
175            return;
176         }
177
178         lv_obj_t * obj = lv_image_create(lv_screen_active());
179         lv_image_set_src(widget, "A:/spiffs/logo.bin");
180         lv_obj_center(widget);
181      }
182
183- **Build and flash**
184
185   After calling ``idf.py build flash`` the picture should be displayed on the screen.
186
187
188.. note::
189
190   Changes made by ``menuconfig`` are not being tracked in the repository if the ``sdkconfig`` file is added to ``.gitignore``, which is the default for many ESP-IDF projects.
191   To make your configuration permanent, add the following lines to ``sdkconfig.defaults``:
192
193   .. code:: c
194
195      CONFIG_PARTITION_TABLE_CUSTOM=y
196      CONFIG_LV_USE_FS_STDIO=y
197      CONFIG_LV_FS_STDIO_LETTER=65
198      CONFIG_LV_FS_DEFAULT_DRIVER_LETTER=65
199