mirror of
https://github.com/lvgl/lvgl.git
synced 2026-05-10 04:37:55 +08:00
docs(espressif): update esp32 documentation (#8830)
Signed-off-by: Felipe Neves <felipe@lvgl.io> Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
This commit is contained in:
Felipe Neves
GitHub
+130
@@ -0,0 +1,130 @@
|
||||
.. _lvgl_esp_idf:
|
||||
|
||||
================================
|
||||
Add LVGL to an ESP32 IDF project
|
||||
================================
|
||||
|
||||
|
||||
LVGL can be used and configured as a standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Using LVGL in Your ESP-IDF Project
|
||||
**********************************
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
--------------
|
||||
|
||||
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-block:: sh
|
||||
|
||||
idf.py add-dependency "lvgl/lvgl^9.*"
|
||||
|
||||
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.
|
||||
|
||||
**Advanced usage: Use LVGL as local component**
|
||||
|
||||
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-block:: sh
|
||||
|
||||
git submodule add https://github.com/lvgl/lvgl.git components/lvgl
|
||||
|
||||
.. note::
|
||||
|
||||
All components from ``${project_dir}/components`` are automatically added to the build.
|
||||
|
||||
Display Integration
|
||||
-------------------
|
||||
|
||||
For a 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.
|
||||
|
||||
- esp_lcd natively supports 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
|
||||
|
||||
These components share a common public API, making it easy to migrate your projects across different display and touch drivers.
|
||||
|
||||
To add a display or touch driver to your project, use a command like:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0"
|
||||
|
||||
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``.
|
||||
|
||||
Addtionally the user can make the current LVGL settings permanent, or default, for the current
|
||||
project, all that is needed is to create a file on the project root called
|
||||
`sdkconfig.defaults` and move the `CONFIG_LV_` symbols to that file.
|
||||
|
||||
It is possible to create a per-chip default confiuration files by creating A
|
||||
configuration default files which starts to the chip variant, for example
|
||||
`sdkconfig.esp32p4` will only apply the default configuration for an ESP32-P4
|
||||
IDF project.
|
||||
|
||||
Starting the LVGL component
|
||||
---------------------------
|
||||
|
||||
Once the IDF project and the LVGL component have been configured, all
|
||||
the early initialization process inside of the code will be ready to use, however
|
||||
the user should manually start the LVGL subsystem for IDF by calling `bsp_display_start()`,
|
||||
or `lvgl_port_init()` if LVGL was manually configured, for example without using
|
||||
the `esp_bsp` component.
|
||||
|
||||
After calling this function, LVGL will be running in the background; that is,
|
||||
unlike the usual approach, there is no need to periodically call :cpp:expr:`lv_timer_handler()`,
|
||||
this function is called by a background task managed by the IDF.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
bsp_display_start();
|
||||
bsp_display_backlight_on();
|
||||
|
||||
bsp_display_lock(0);
|
||||
lv_demo_benchmark();
|
||||
bsp_display_unlock();
|
||||
}
|
||||
|
||||
For cases when the `esp_bsp` is not being used, it is possible to invoke
|
||||
the ESP-LVGL port directly:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
void app_main(void)
|
||||
{
|
||||
const lvgl_port_cfg_t lvgl_cfg = ESP_LVGL_PORT_INIT_CONFIG();
|
||||
esp_err_t err = lvgl_port_init(&lvgl_cfg);
|
||||
|
||||
lv_demo_benchmark();
|
||||
}
|
||||
|
||||
Building and Flashing
|
||||
---------------------
|
||||
|
||||
Building an IDF project that features the LVGL usage, is similar to any other
|
||||
project, by using IDF through the command line the user can combine various
|
||||
commands into a single prompt:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
idf.py build flash monitor
|
||||
|
||||
After the flashing the monitor console will be launched automatically.
|
||||
@@ -0,0 +1,66 @@
|
||||
.. _esp_dma2d:
|
||||
|
||||
=======================================
|
||||
2D Direct Memory Access (DMA2D) Support
|
||||
=======================================
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Some chips from Espressif such as the ESP32-P4 family features a peripheral
|
||||
that enhances the copy of 2-D data from a place to another, including output
|
||||
this 2-D data to other peripherals.
|
||||
|
||||
This peripheral is the 2-D direct memory access, or DMA2D, the Espressif
|
||||
SDK, the IDF, offers a full featured driver for the DMA2D that is automatically
|
||||
enabled on the supported chips.
|
||||
|
||||
One of its primary role is to serve as support for the Pixel Processor Accelerator
|
||||
the PPA, being used to copy the source image data to the desired PPA client splitting
|
||||
these data into fixed size blocks, called bursts. Also the DMA2D is used to pick the
|
||||
output chunks from the PPA client and copy over to the destination buffer, or the display
|
||||
frame-buffer.
|
||||
|
||||
More information about PPA can be found in: :ref:`PPA (Pixel Processing Accelerator) Support <esp_ppa>`.
|
||||
|
||||
Interacting to the DMA2D
|
||||
------------------------
|
||||
|
||||
The LVGL does not interact directly to the DMA2D, instead, the Espressif LVGL port component
|
||||
display driver uses the DMA2D to copy the target drawn buffer to the display buffer without CPU
|
||||
intervention. Even though this option is available the user is responsible to explicitly enable
|
||||
it on the display driver of the LVGL port component.
|
||||
|
||||
To enabling it the user should set on its `sdkconfig.defaults` the `CONFIG_BSP_DISPLAY_LVGL_AVOID_TEAR`,
|
||||
which will tell the driver to use the DMA2D to optimize transfer. Please notice that enabling
|
||||
this option will be only available when using the PSRAM memory and double buffer mode, otherwise
|
||||
a compiler error will be raised.
|
||||
|
||||
If the user is configuring the display manually, it is possible to enable the DMA2D in runtime by
|
||||
setting the DMA2D flag to true:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/* Gets the default configuration for the MIPI display controller */
|
||||
esp_lcd_dpi_panel_config_t dpi_config = EK79007_1024_600_PANEL_60HZ_CONFIG(LCD_COLOR_PIXEL_FORMAT_RGB888);
|
||||
|
||||
/* Explictly set the DMA2D to assist the buffer transfer */
|
||||
dpi_config.flags.use_dma2d = true;
|
||||
|
||||
ek79007_vendor_config_t vendor_config = {
|
||||
.mipi_config = {
|
||||
.dsi_bus = mipi_dsi_bus,
|
||||
.dpi_config = &dpi_config,
|
||||
},
|
||||
};
|
||||
|
||||
esp_lcd_panel_dev_config_t lcd_dev_config = {
|
||||
.reset_gpio_num = UI_FIRMWARE_PIN_NUM_LCD_RST,
|
||||
.rgb_ele_order = LCD_RGB_ELEMENT_ORDER_RGB,
|
||||
.bits_per_pixel = 24,
|
||||
.vendor_config = &vendor_config,
|
||||
};
|
||||
|
||||
/* Configures and enable the display */
|
||||
ESP_ERROR_CHECK(esp_lcd_new_panel_ek79007(mipi_dbi_io, &lcd_dev_config, &mipi_dpi_panel));
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
.. _esp_ppa:
|
||||
|
||||
==========================================
|
||||
PPA (Pixel Processing Accelerator) Support
|
||||
==========================================
|
||||
|
||||
Overview
|
||||
********
|
||||
|
||||
Some ESP32 chip series, like the ESP32-P4 support the Pixel Processing Accelerator hardware (PPA), which is capable of
|
||||
speeding-up the filling and image blending operations, this peripheral works with the
|
||||
DMA-2D hardware which is responsible to move the input/output buffers into/from the PPA processing engine.
|
||||
|
||||
Supported devices
|
||||
-----------------
|
||||
|
||||
The Espressif targets that support the PPA are:
|
||||
|
||||
- ESP32-P4 series.
|
||||
|
||||
|
||||
Using the LVGL PPA draw unit on your ESP-IDF project
|
||||
****************************************************
|
||||
|
||||
LVGL supports, in experimental level, the filling and the image blending
|
||||
acceleration through the PPA, the user can enable it in their ``sdkconfig.defaults`` by
|
||||
adding the following option to enable the PPA draw unit in conjunction with the software renderer:
|
||||
|
||||
.. code:: c
|
||||
|
||||
CONFIG_LV_USE_PPA=y
|
||||
|
||||
Save the file and then rebuild the project, this will be sufficient to add the PPA code and it will start to run automatically, so
|
||||
no further steps are required from the user code perspective.
|
||||
|
||||
Benchmarking
|
||||
------------
|
||||
|
||||
When running the `lv_demo_benchmark` from LVGL the user can compare the performance when
|
||||
the PPA is enabled versus the pure software rendering, by using the latest version of the
|
||||
LVGL and LVGL port component it can be observed an average saving of 30% of the rendering
|
||||
time for draw tasks that are image and rectangle fill. On some cases for pure filling on
|
||||
integer multiples of the display size it is possible to observe up 9x of speed increase when
|
||||
the PPA is enabled.
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
Please notice that the PPA is at experimental level where some performance gains are expected on drawing tasks related
|
||||
to rectangle copy or filling, while for image blending, even though it is operational, there are no significant gains,
|
||||
the initial cause for that according to the PPA section from reference manual is due to the DMA-2D memory bandwidth.
|
||||
|
||||
|
||||
Using the Espressif LVGL component PPA features
|
||||
***********************************************
|
||||
|
||||
The Espressif IDF LVGL port component also offers hardware acceleration
|
||||
for the display operations, that is it, once the LVGL render completes
|
||||
an operation and the draw buffer is already handled to the display driver,
|
||||
the Espressif component can optionally perform mirror and rotation of
|
||||
the rendered data using hardware assistance.
|
||||
|
||||
The LVGL display driver for Espressif operates by reading the
|
||||
descriptor of the drawn data to check if rotation and mirror are flags
|
||||
set on the data properties, in positive case, before sending the data
|
||||
to the display, the mirror and rotation are performed first using the
|
||||
PPA rotation and mirror client.
|
||||
|
||||
When compared to pure software rotation, using the PPA to rotate the objects
|
||||
can save up 40% of rendering time in average, while keeping the CPU in idle
|
||||
saving power, or using it to perform other tasks, PPA rotation is asynchronous,
|
||||
and once started it will signal the application using its dedicated interrupt.
|
||||
|
||||
To enable such behavior on the display driver, the PPA acceleration should
|
||||
be set on the project `sdkconfig.defaults` via the symbol `CONFIG_LVGL_PORT_ENABLE_PPA`,
|
||||
setting it to true will make the hardware assistance for image rotation and mirroring
|
||||
automatic. No extra code is required.
|
||||
|
||||
Please notice that such option can be set via menuconfig using the
|
||||
standard IDF command for configuration: `idf.py menuconfig`.
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
.. API startswith: lv_draw_ppa_
|
||||
@@ -8,5 +8,7 @@ Espressif
|
||||
:maxdepth: 2
|
||||
|
||||
overview
|
||||
ppa_gpu
|
||||
|
||||
add_lvgl_to_esp32_idf_project
|
||||
hardware_accelerator_dma2d
|
||||
hardware_accelerator_ppa
|
||||
tips_and_tricks
|
||||
|
||||
@@ -2,233 +2,70 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
LVGL can be used and configured as standard `ESP-IDF <https://github.com/espressif/esp-idf>`__ component.
|
||||
About
|
||||
*****
|
||||
|
||||
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.
|
||||
Espressif Systems is a fabless chip manufacturer that produces the ESP32 series of
|
||||
system on chips, these chips can be based on Xtensa or Risc-V architectures, and they
|
||||
feature the common set of analog and digital peripherals of a general purpose microcontroller
|
||||
combined to a radio subsystem capable to run a Bluetooth and/or a WiFi stack.
|
||||
|
||||
Espressif System also provides its comprehensive software development kit (SDK) for
|
||||
users to focus only in their applications, which is the IDF, all other 3rd party
|
||||
support such as Arduino, Zephyr, NuttX and Micropython are built on top of the IDF or
|
||||
some of its components.
|
||||
|
||||
LVGL Demo Projects for ESP32
|
||||
----------------------------
|
||||
|
||||
For a quick start with LVGL and ESP32, the following pre-configured demo projects are available for specific development boards:
|
||||
Application Development
|
||||
***********************
|
||||
|
||||
- `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>`__
|
||||
The LVGL is supported by Espressif SDK, that is it, the IDF as mentioned before,
|
||||
therefore ESP32 series of chips are supported on a different sets of frameworks
|
||||
called by Espressif as 3rd party projects.
|
||||
|
||||
Refer to the README.md files in these repositories for build and flash instructions.
|
||||
This guide will cover the usage of the LVGL using the Espressif-IDF software development
|
||||
kit. Although ESP32 are supported on other frameworks also supported by LVGL, it
|
||||
is recommended the user to check the following pages:
|
||||
|
||||
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.
|
||||
- :ref:`Arduino Framework <arduino>`
|
||||
- :ref:`Platformio <platformio>`
|
||||
- :ref:`MicroPython <micropython>`
|
||||
- :ref:`NuttX RTOS <nuttx>`
|
||||
- :ref:`Zephyr RTOS <zephyr>`
|
||||
|
||||
On the pages above users would be able to check the respective getting started on
|
||||
these platforms where ESP32, and other chips are abstracted by the framework.
|
||||
|
||||
Using LVGL in Your ESP-IDF Project
|
||||
----------------------------------
|
||||
Ready to use projects
|
||||
*********************
|
||||
|
||||
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.
|
||||
For a quick start with LVGL and ESP32, the LVGL maintains an demo project compatible to
|
||||
several ESP32 boards under its `LV Port for ESP32 <https://github.com/lvgl/lv_esp_idf>`.
|
||||
|
||||
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:
|
||||
Refer to the README.md files in this repository for quick build and
|
||||
flash instructions.
|
||||
|
||||
.. code:: sh
|
||||
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.
|
||||
|
||||
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.
|
||||
LVGL Support for ESP32 Graphical Peripherals
|
||||
********************************************
|
||||
|
||||
Obtaining LVGL
|
||||
~~~~~~~~~~~~~~
|
||||
Some of the ESP32 chips like the ESP32P4 family have built-in support
|
||||
for driving display through standard interfaces like RGB and MIPI,
|
||||
the Espressif IDF (esp-idf), provides the necessary drivers, leaving
|
||||
to the user the responsibility to integrate them into the LVGL display
|
||||
subsystem.
|
||||
|
||||
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:
|
||||
Espressif, via its component manager system, provides a ready to use
|
||||
LVGL porting component, which is the recommended and preferred way of
|
||||
integrating input and output devices from the ESP32 chip to the LVGL
|
||||
Display subsystem, this component is covered in
|
||||
:ref:`Add LVGL to an ESP32 IDF project <lvgl_esp_idf>`
|
||||
|
||||
.. code-block:: sh
|
||||
Besides the display controller, some ESP32 chips offer graphical hardware
|
||||
acceleration peripherals like:
|
||||
|
||||
idf.py add-dependency "lvgl/lvgl^9.*"
|
||||
|
||||
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.
|
||||
|
||||
**Advanced usage: Use LVGL as local component**
|
||||
|
||||
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-block:: sh
|
||||
|
||||
git submodule add https://github.com/lvgl/lvgl.git components/lvgl
|
||||
|
||||
.. note::
|
||||
|
||||
All components from ``${project_dir}/components`` are automatically added to build.
|
||||
|
||||
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.
|
||||
|
||||
- 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
|
||||
|
||||
These components share a common public API, making it easy to migrate your projects across different display and touch drivers.
|
||||
|
||||
To add a display or touch driver to your project, use a command like:
|
||||
|
||||
.. code-block:: sh
|
||||
|
||||
idf.py add-dependency "espressif/esp_lcd_gc9a01^2.0.0"
|
||||
|
||||
Using the File System under ESP-IDF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
ESP-IDF uses the standard C file operation functions (``fopen``, ``fread``) in all its storage related APIs.
|
||||
This allows seamless interoperability with LVGL when enabling the :c:macro:`LV_USE_FS_STDIO` configuration.
|
||||
The process is described in details below, using ``SPIFFS`` as demonstration.
|
||||
|
||||
- **Decide what storage system you want to use**
|
||||
|
||||
ESP-IDF has many, ready-to-use examples like
|
||||
`SPIFFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/spiffsgen>`__
|
||||
,
|
||||
`SD Card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdspi>`__
|
||||
and
|
||||
`LittleFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/littlefs>`__
|
||||
.
|
||||
|
||||
- **Re-configure your own project**
|
||||
|
||||
The example project should be examined for details, but in general the changes involve:
|
||||
|
||||
- Enabling LVGL's STDIO file system in the configuration
|
||||
|
||||
You can use ``menuconfig``:
|
||||
|
||||
- ``Component config → LVGL configuration → 3rd Party Libraries``: enable ``File system on top of stdio API``
|
||||
- Then select ``Set an upper cased letter on which the drive will accessible`` and set it to ``65`` (ASCII **A**)
|
||||
- You can also set ``Default driver letter`` to 65 to skip the prefix in file paths.
|
||||
|
||||
- Modifying the partition table
|
||||
|
||||
The exact configuration depends on your flash size and existing partitions,
|
||||
but the new final result should look something like this:
|
||||
|
||||
.. csv-table:: Partition Table
|
||||
|
||||
nvs, data, nvs, 0x9000, 0x6000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1400k
|
||||
storage, data, spiffs, , 400k
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you are not using a custom ``partition.csv`` yet, it can be added
|
||||
via ``menuconfig`` (``Partition Table → Partition Table → Custom partition table CSV``).
|
||||
|
||||
- Apply changes to the build system
|
||||
|
||||
Some ESP file systems provide automatic generation from a host folder using CMake. The proper line(s) must be copied to ``main/CMakeLists.txt``
|
||||
|
||||
.. note::
|
||||
|
||||
``LittleFS`` has extra dependencies that should be added to ``main/idf_component.yml``
|
||||
|
||||
- **Prepare the image files**
|
||||
|
||||
LVGL's ``LVGLImage.py`` Python tool can be used to convert images to binary pixel map files.
|
||||
It supports various formats and compression.
|
||||
|
||||
Meanwhile 3rd party libraries
|
||||
(like :ref:`LodePNG<lodepng_rst>` and :ref:`Tiny JPEG<tjpgd>`)
|
||||
allow using image files without conversion.
|
||||
|
||||
After preparing the files, they should be moved to the target device:
|
||||
|
||||
- If properly activated a **SPIFFS** file system based on the ``spiffs_image`` folder should be automatically generated and later flashed to the target
|
||||
- Similar mechanism for **LittleFS** uses the ``flash_data`` folder, but it's only available for Linux hosts
|
||||
- For the **SD Card**, a traditional file browser can be used
|
||||
|
||||
- **Invoke proper API calls in the application code**
|
||||
|
||||
The core functionality requires only a few lines. The following example draws the image as well.
|
||||
|
||||
.. code:: c
|
||||
|
||||
#include "esp_spiffs.h"
|
||||
|
||||
void lv_example_image_from_esp_fs(void) {
|
||||
|
||||
esp_vfs_spiffs_conf_t conf = {
|
||||
.base_path = "/spiffs",
|
||||
.partition_label = NULL,
|
||||
.max_files = 5,
|
||||
.format_if_mount_failed = false
|
||||
};
|
||||
|
||||
esp_err_t ret = esp_vfs_spiffs_register(&conf);
|
||||
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to register SPIFF filesystem");
|
||||
return;
|
||||
}
|
||||
|
||||
lv_obj_t * obj = lv_image_create(lv_screen_active());
|
||||
lv_image_set_src(widget, "A:/spiffs/logo.bin");
|
||||
lv_obj_center(widget);
|
||||
}
|
||||
|
||||
- **Build and flash**
|
||||
|
||||
After calling ``idf.py build flash`` the picture should be displayed on the screen.
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
To make your configuration permanent, add the following lines to ``sdkconfig.defaults``:
|
||||
|
||||
.. code:: c
|
||||
|
||||
CONFIG_PARTITION_TABLE_CUSTOM=y
|
||||
CONFIG_LV_USE_FS_STDIO=y
|
||||
CONFIG_LV_FS_STDIO_LETTER=65
|
||||
CONFIG_LV_FS_DEFAULT_DRIVER_LETTER=65
|
||||
|
||||
Support for Pixel Processing Accelerator
|
||||
----------------------------------------
|
||||
|
||||
Some ESP32 chip series, like the ESP32-P4 support the Pixel Processing Accelerator hardware (PPA), which is capable of
|
||||
speeding-up the filling and image blending operations, this peripheral works with the
|
||||
DMA-2D hardware which is responsible to move the input/output buffers into/from the PPA processing engine.
|
||||
|
||||
Supported devices
|
||||
-----------------
|
||||
|
||||
The Espressif targets that supports the PPA are:
|
||||
|
||||
- ESP32-P4 series.
|
||||
|
||||
|
||||
Using the PPA on your ESP-IDF project
|
||||
-------------------------------------
|
||||
|
||||
LVGL supports, in experimental level, the filling and the image blending
|
||||
acceleration through the PPA, the user can enable it inside their ``sdkconfig.default`` by
|
||||
adding the following option to enable the PPA draw unit in conjunction to the software render:
|
||||
|
||||
.. code:: c
|
||||
|
||||
CONFIG_LV_USE_PPA=y
|
||||
|
||||
Save the file and then rebuild the project, this will be sufficient to add the PPA code and it will start to run automatically, so
|
||||
no further steps are required from the user code perspective.
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
Please notice that the PPA is at experimental level where some performance gains are expected on drawing tasks related
|
||||
to rectangle copy or filling, while for image blending, even though it is operational, there is no significant gains,
|
||||
the initial cause for that according to the PPA section from reference manual is due to the DMA-2D memory bandwidth.
|
||||
- :ref:`Support 2D Direct Memory Access (DMA2D) <esp_dma2d>`
|
||||
- :ref:`Support for Pixel Processing Accelerator <esp_ppa>`
|
||||
|
||||
@@ -1,8 +0,0 @@
|
||||
======================================
|
||||
Espressif Pixel Processing Accelerator
|
||||
======================================
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
.. API startswith: lv_draw_ppa_
|
||||
@@ -0,0 +1,241 @@
|
||||
===============
|
||||
Tips and tricks
|
||||
===============
|
||||
|
||||
|
||||
Improving LVGL speed of execution
|
||||
*********************************
|
||||
|
||||
The IDF project in general are configured to optimize the final application image
|
||||
in respect of its size. For some LVGL applications this may not be desired or will
|
||||
result on poor speed of execution.
|
||||
|
||||
In this case, it is interesting to set some of the IDF project wide options on the
|
||||
`sdkconfig.defaults` such as:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_COMPILER_OPTIMIZATION_PERF=y
|
||||
|
||||
This one will compile the application with performance as priority, using SIMD
|
||||
instructions where is possible. It is possible to perceive an increase up to 30%
|
||||
of overall speed execution increment.
|
||||
|
||||
it is also possible to speed-up the execution of the critical code of the LVGL, by
|
||||
telling the compiler to put these sections on the IRAM area of ESP32 chips setting
|
||||
the following option:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_LV_ATTRIBUTE_FAST_MEM_USE_IRAM=y
|
||||
|
||||
It is also possible to set the CPU to always run on its maximum speed by
|
||||
setting the `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_` option, the value of the
|
||||
frequency varies from chip to chip, for example P4 families support 360MHz:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_360
|
||||
|
||||
And ESP32/ESP32-S3 support 240MHz:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240
|
||||
|
||||
Please notice, some of these options needs to be enabled by setting the IDF
|
||||
experimental options to true:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_IDF_EXPERIMENTAL_FEATURES=y
|
||||
|
||||
|
||||
Configuring the PSRAM on ESP32 supported devices
|
||||
************************************************
|
||||
|
||||
Some of the high-end chips of ESP32 features an external memory on its module, it is
|
||||
Pseudo-Static Random Access Memory, the PSRAM. In general values from 4 to 16MB are
|
||||
present on the chip and LVGL can take a portion of this memory to:
|
||||
|
||||
- Copy read-only objects from Flash to PSRAM to increase speed.
|
||||
- Use direct-mode plus dual buffer even on ESP32 that does not have built-in display controller.
|
||||
|
||||
In both scenarios the result will be reflected on less time to flush data to the
|
||||
display, resulting in higher frame-rates. To enable the PSRAM usage the user should:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_SPIRAM=y
|
||||
CONFIG_SPIRAM_MODE_HEX=y
|
||||
CONFIG_SPIRAM_USE=y
|
||||
CONFIG_SPIRAM_ALLOW_BSS_SEG_EXTERNAL_MEMORY=y
|
||||
CONFIG_SPIRAM_RODATA=y
|
||||
|
||||
These options can reside on the IDF project `sdkconfig.defaults`, the last option
|
||||
|
||||
|
||||
Application crashes when enabling PPA
|
||||
*************************************
|
||||
|
||||
Is it possible to happen of an application to start crashing because the user
|
||||
enabled `CONFIG_LV_USE_PPA` option. The typical symptom is the appearance of
|
||||
a message on the monitor console that indicates error when esp32 calls the
|
||||
`esp_msync` function.
|
||||
|
||||
This happens because PPA only accepts chunks of data that are aligned to the
|
||||
cache L1 line size, that is it 64-bytes, even though the PPA draw unit handles
|
||||
the alignment of the source buffer, the target draw buffer area should be also
|
||||
aligned otherwise the transfer from PPA to it may fail. To prevent this
|
||||
behavior is interesting to make `CONFIG_LV_DRAW_BUF_ALIGN` to be a multiple of the
|
||||
cache L1 line size, that is it, set its value to `64` instead of the default of `4`.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_LV_DRAW_BUF_ALIGN=64
|
||||
|
||||
|
||||
EPS32-P4 monitor log reports buffer underrun and frame-rate decreases
|
||||
*********************************************************************
|
||||
|
||||
In cases when the PSRAM is enabled and the PPA is used, it is common to see
|
||||
frame-rate degradation followed by a message on the log that reports the display
|
||||
buffer will underrun. This behavior happens because depending the IDF version the
|
||||
PSRAM was not enabled with maximum supported speed.
|
||||
|
||||
To fix that behavior just add to the `sdkconfig.defaults` the following option:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_SPIRAM_SPEED_200M=y
|
||||
|
||||
|
||||
Enabling LVGL logs on IDF project
|
||||
*********************************
|
||||
|
||||
The LVGL logs are not enabled by default, for enable it, add the following
|
||||
options on the `sdkconfig.defaults`:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
CONFIG_LV_USE_LOG=y
|
||||
CONFIG_LV_LOG_LEVEL_INFO=y
|
||||
CONFIG_LV_LOG_PRINTF=y
|
||||
|
||||
The logging subsystem of LVGL relies on the ESP-IDF presence of the
|
||||
printf.
|
||||
|
||||
Using the File System under ESP-IDF
|
||||
***********************************
|
||||
|
||||
ESP-IDF uses the standard C file operation functions (``fopen``, ``fread``) in all its storage related APIs.
|
||||
This allows seamless interoperability with LVGL when enabling the :c:macro:`LV_USE_FS_STDIO` configuration.
|
||||
The process is described in details below, using ``SPIFFS`` as demonstration.
|
||||
|
||||
- **Decide what storage system you want to use**
|
||||
|
||||
ESP-IDF has many, ready-to-use examples like
|
||||
`SPIFFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/spiffsgen>`__
|
||||
,
|
||||
`SD Card <https://github.com/espressif/esp-idf/tree/master/examples/storage/sd_card/sdspi>`__
|
||||
and
|
||||
`LittleFS <https://github.com/espressif/esp-idf/tree/master/examples/storage/littlefs>`__
|
||||
.
|
||||
|
||||
- **Re-configure your own project**
|
||||
|
||||
The example project should be examined for details, but in general the changes involve:
|
||||
|
||||
- Enabling LVGL's STDIO file system in the configuration
|
||||
|
||||
You can use ``menuconfig``:
|
||||
|
||||
- ``Component config → LVGL configuration → 3rd Party Libraries``: enable ``File system on top of stdio API``
|
||||
- Then select ``Set an upper cased letter on which the drive will accessible`` and set it to ``65`` (ASCII **A**)
|
||||
- You can also set ``Default driver letter`` to 65 to skip the prefix in file paths.
|
||||
|
||||
- Modifying the partition table
|
||||
|
||||
The exact configuration depends on your flash size and existing partitions,
|
||||
but the new final result should look something like this:
|
||||
|
||||
.. csv-table:: Partition Table
|
||||
|
||||
nvs, data, nvs, 0x9000, 0x6000
|
||||
phy_init, data, phy, 0xf000, 0x1000
|
||||
factory, app, factory, 0x10000, 1400k
|
||||
storage, data, spiffs, , 400k
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
If you are not using a custom ``partition.csv`` yet, it can be added
|
||||
via ``menuconfig`` (``Partition Table → Partition Table → Custom partition table CSV``).
|
||||
|
||||
- Apply changes to the build system
|
||||
|
||||
Some ESP file systems provide automatic generation from a host folder using CMake. The proper line(s) must be copied to ``main/CMakeLists.txt``
|
||||
|
||||
.. note::
|
||||
|
||||
``LittleFS`` has extra dependencies that should be added to ``main/idf_component.yml``
|
||||
|
||||
- **Prepare the image files**
|
||||
|
||||
LVGL's ``LVGLImage.py`` Python tool can be used to convert images to binary pixel map files.
|
||||
It supports various formats and compression.
|
||||
|
||||
Meanwhile 3rd party libraries
|
||||
(like :ref:`LodePNG<lodepng_rst>` and :ref:`Tiny JPEG<tjpgd>`)
|
||||
allow using image files without conversion.
|
||||
|
||||
After preparing the files, they should be moved to the target device:
|
||||
|
||||
- If properly activated a **SPIFFS** file system based on the ``spiffs_image`` folder should be automatically generated and later flashed to the target
|
||||
- Similar mechanism for **LittleFS** uses the ``flash_data`` folder, but it's only available for Linux hosts
|
||||
- For the **SD Card**, a traditional file browser can be used
|
||||
|
||||
- **Invoke proper API calls in the application code**
|
||||
|
||||
The core functionality requires only a few lines. The following example draws the image as well.
|
||||
|
||||
.. code:: c
|
||||
|
||||
#include "esp_spiffs.h"
|
||||
|
||||
void lv_example_image_from_esp_fs(void) {
|
||||
|
||||
esp_vfs_spiffs_conf_t conf = {
|
||||
.base_path = "/spiffs",
|
||||
.partition_label = NULL,
|
||||
.max_files = 5,
|
||||
.format_if_mount_failed = false
|
||||
};
|
||||
|
||||
esp_err_t ret = esp_vfs_spiffs_register(&conf);
|
||||
|
||||
if (ret != ESP_OK) {
|
||||
ESP_LOGE(TAG, "Failed to register SPIFF filesystem");
|
||||
return;
|
||||
}
|
||||
|
||||
lv_obj_t * obj = lv_image_create(lv_screen_active());
|
||||
lv_image_set_src(widget, "A:/spiffs/logo.bin");
|
||||
lv_obj_center(widget);
|
||||
}
|
||||
|
||||
- **Build and flash**
|
||||
|
||||
After calling ``idf.py build flash`` the picture should be displayed on the screen.
|
||||
|
||||
.. note::
|
||||
|
||||
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.
|
||||
To make your configuration permanent, add the following lines to ``sdkconfig.defaults``:
|
||||
|
||||
.. code:: c
|
||||
|
||||
CONFIG_PARTITION_TABLE_CUSTOM=y
|
||||
CONFIG_LV_USE_FS_STDIO=y
|
||||
CONFIG_LV_FS_STDIO_LETTER=65
|
||||
CONFIG_LV_FS_DEFAULT_DRIVER_LETTER=65
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _arduino:
|
||||
|
||||
=======
|
||||
Arduino
|
||||
=======
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _platformio:
|
||||
|
||||
==========
|
||||
PlatformIO
|
||||
==========
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _nuttx:
|
||||
|
||||
==========
|
||||
NuttX RTOS
|
||||
==========
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
.. _zephyr:
|
||||
|
||||
======
|
||||
Zephyr
|
||||
======
|
||||
|
||||
Reference in New Issue
Block a user