forked from lvgl/lvgl
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs(espressif): Update Espressif's documentation with esp_lvgl_port
Also update demos section with updated links
- Loading branch information
1 parent
6264265
commit 2be5651
Showing
1 changed file
with
41 additions
and
44 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,85 +1,82 @@ | ||
| ============================= | ||
| Espressif (ESP32 chip series) | ||
| Espressif (ESP32 Chip Series) | ||
| ============================= | ||
|
|
||
| LVGL can be used and configured as a standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component. | ||
| LVGL can be used and configured as standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component. | ||
|
|
||
| More information about ESP-IDF build system can be found `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html>`__. | ||
| If 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. | ||
|
|
||
|
|
||
| LVGL demo project for ESP32 | ||
| LVGL Demo Projects for ESP32 | ||
| --------------------------- | ||
|
|
||
| We've created `lv_port_esp32 <https://github.com/lvgl/lv_port_esp32>`__, | ||
| a project using ESP-IDF and LVGL to show one of the demos from | ||
| `demos <https://github.com/lvgl/lvgl/demos>`__. You can configure the | ||
| project to use one of the many supported display controllers and targets | ||
| (chips). | ||
| For a quick start with LVGL and ESP32, the following pre-configured demo projects are available for specific development boards: | ||
|
|
||
| See `lvgl_esp32_drivers <https://github.com/lvgl/lvgl_esp32_drivers>`__ | ||
| repository for a complete list of supported display and indev (touch) | ||
| controllers and targets. | ||
| - `ESP-BOX-3 <https://github.com/lvgl/lv_port_espressif_esp-box-3>`__ | ||
| - `ESP32-S3-LCD-EV-BOARD <https://github.com/lvgl/lv_port_espressif_esp32-s3-lcd-ev-board>`__ | ||
| - `M5Stack-CoreS3 <https://github.com/lvgl/lv_port_espressif_M5Stack_CoreS3>`__ | ||
|
|
||
| Refer to the README.md files in these repositories for build and flash instructions. | ||
|
|
||
| Using LVGL in your ESP-IDF project | ||
| These 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. | ||
|
|
||
|
|
||
| Using LVGL in Your ESP-IDF Project | ||
| ---------------------------------- | ||
|
|
||
| Prerequisites | ||
| ~~~~~~~~~~~~~ | ||
| The 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. | ||
|
|
||
| The 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: | ||
|
|
||
| .. code:: sh | ||
| - ESP-IDF v4.1 and above | ||
| - ESP evaluation board with a display | ||
| idf.py add-dependency "espressif/esp_lvgl_port^2.3.0" | ||
| By 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. | ||
|
|
||
| Obtaining LVGL | ||
| ~~~~~~~~~~~~~~ | ||
|
|
||
| **Option 1:** git submodule | ||
|
|
||
| Simply clone LVGL into your ``project_root/components`` directory and it | ||
| will be automatically integrated into the project. If the project is a | ||
| git repository you can include LVGL as a git submodule: | ||
| LVGL is distributed through `ESP Registry <https://components.espressif.com/>`__, where all LVGL releases are uploaded. | ||
| In 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: | ||
|
|
||
| .. code:: sh | ||
| git submodule add https://github.com/lvgl/lvgl.git components/lvgl | ||
| idf.py add-dependency lvgl/lvgl^9.* | ||
| The above command will clone LVGL's main repository into the | ||
| ``components/lvgl`` directory. LVGL includes a ``CMakeLists.txt`` file | ||
| that sets some configuration options so you can use LVGL right away. | ||
| Adjust 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. | ||
|
|
||
| **Option 2:** IDF Component Manager | ||
| **Advanced usage: Use LVGL as local component** | ||
|
|
||
| LVGL is also distributed through `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html>`__. | ||
| It allows users to seamlessly integrate `LVGL component <https://components.espressif.com/component/lvgl/lvgl>`__ into | ||
| their project with following command: | ||
| For 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: | ||
|
|
||
| .. code:: sh | ||
| idf.py add-dependency lvgl/lvgl>=8.* | ||
| git submodule add https://github.com/lvgl/lvgl.git components/lvgl | ||
| During next project build, LVGL component will be fetched from the | ||
| component registry and added to project build. | ||
| .. note:: | ||
|
|
||
| All components from ``${project_dir}/components`` are automatically added to build. | ||
|
|
||
| Configuration | ||
| ~~~~~~~~~~~~~ | ||
|
|
||
| When you are ready to configure LVGL, launch the configuration menu with | ||
| ``idf.py menuconfig`` in your project root directory, go to | ||
| ``Component config`` and then ``LVGL configuration``. | ||
| To configure LVGL, launch the configuration menu with ``idf.py menuconfig`` in your project root directory. Navigate to ``Component config`` and then ``LVGL configuration``. | ||
|
|
||
|
|
||
| Support for Display and Touch Drivers | ||
| ------------------------------------- | ||
|
|
||
| For 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. | ||
|
|
||
| Using lvgl_esp32_drivers in ESP-IDF project | ||
| ------------------------------------------- | ||
| - esp_lcd natively supports for some `basic displays <https://github.com/espressif/esp-idf/tree/master/components/esp_lcd/src>`__ | ||
| - Other displays are maintained in `esp-bsp repository <https://github.com/espressif/esp-bsp/tree/master/components/lcd>`__ and are uploaded to ESP Registry | ||
| - 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 | ||
|
|
||
| You can also add ``lvgl_esp32_drivers`` as a "component". This component | ||
| should be located inside a directory named "components" in your project | ||
| root directory. | ||
| These components share a common public API, making it easy to migrate your projects across different display and touch drivers. | ||
|
|
||
| When your project is a git repository you can include | ||
| ``lvgl_esp32_drivers`` as a git submodule: | ||
| To add a display or touch driver to your project, use a command like: | ||
|
|
||
| .. code:: sh | ||
| git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers | ||
| idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0" |