README.md

LVGL project for ESP32 parallel epapers

This is an ESP32 fork project showcasing LVGL v7 with support for several display controllers and touch controllers. The intention is to use the set_px_cb callback to make LVGL work with different epapers that are already supported in EPDiy component (for parallel epapers). As an experimental test also other SPI epaper displays can be used with CalEPD component.

CalEPD is an ESP-IDF component that supports many different SPI epapers and Paralell using EPDiy as a bridge component. So you will find in the linked repository lvgl_epaper_drivers two drivers in the lvgl_tft directory:

• epdiy_epaper.cpp (Display controller module: EPDIY_GENERIC)
• calepd_epaper.cpp (Experimental: lvgl_epaper_drivers component in develop branch)

This drivers are automatically configured when you run idf.py menuconfig selecting this option:

Component config -> LVGL TFT/Epaper controller -> Display controller model

The demo application is the lv_demo_widgets project from the lv_examples repository.

• Version of ESP-IDF required 4.2. NOTE: Usage of idf.py to compile/flash is encouraged.
• Version of LVGL used: 7.9.
• Version of lv_examples used: 7.9.
• Important please use lvgl component in branch release/v7 and this main repository in master branch.
• SPI epapers supported in CalEPD can be used but then VSPI should be selected in LVGL. There is a CalEPD driver but this fork is mainly focused on making it work with fast parallel epapers supported by EPDiy component.

The main idea is to use a bridge driver that pushes the pixels to EPDiy using the set_px_cb/flush callbacks in order to render the layouts on the supported epapers. This will have a performance hit but it will also allow us to draw UX interfaces in parallel epapers that are quite fast flushing partial refresh. Using CalEPD driver is only experimental and to test edge cases, like complex 4 SPI combined displays, that are not supported at the moment in LVGL. L58 Touch driver that EPD47 uses is also added using as a bridge component FT6x36. First test target is Lilygo EPD47. This parallel epaper comes with an ESP32-WROVER and PSRAM and both epaper and touch module can be adquired for 45 u$ in Aliexpress. Please check the Wiki section and the notes below to understand how to compile your first examples.

Hardware required

For the first's tests the Lilygo EPD47 parallel epaper with the L58 Touch overlay was used. You can find both in Aliexpress Lilygo official store:

Table of content

• Get started
• Use LVGL in your ESP-IDF project
• Use lvgl_esp32_drivers in your project
• Platformio support
• ESP32-S2 Support

Example demo for TFT displays:

Display and touch controllers

The display and touch (indev) controllers are now into it's own repository, you can find it here. To report any issue or add new display or touch (indev) drivers you can do so in the lvgl_esp32_drivers repo.

Get started

Prerequisites

• ESP-IDF Framework.

Note

This project tries to be compatible with both the ESP-IDF v3.x and v4.0, but using v4.0 is recommended. Instructions assume you are using the v4.x toolchain, otherwise use the make commands, e.g. instead of running idf.py menuconfig, run make menuconfig.

Build and run the demo.

1. Clone this project by git clone --recurse-submodules https://github.com/martinberlin/lv_port_esp32-epaper, this will pull this repo and its submodules.

2. Get into the created lv_port_esp32 directory.

3. Run idf.py menuconfig

4. Configure LVGL in Components config->LVGL Configuration. For monochrome displays use the mono theme and we suggest enabling the unscii 8 font.

5. Configure your display and/or touch controllers in Components config->LVGL TFT Display Configuration and Components config->LVGL TOUCH Configuration.

6. Store your project configuration.

7. Build the project with idf.py build

8. If the build don't throw any errors, flash the demo with idf.py -p (YOUR SERIAL PORT) flash (with make this is just make flash - in 3.x PORT is configured in menuconfig)

9. For EPDiy board, Make sure to select the correct board revision and display type in Components E-Paper Driver.

   9.1. Select (X) <LV_THEME_DEFAULT_INIT_MONO> Default init for mono theme in Component config → LVGL configuration → Theme usage → Select theme default init.

   9.2. Uncheck all in Component config → LVGL configuration → Theme usage → Enable theme usage.

Use LVGL in your ESP-IDF project

LVGL now includes a Kconfig file which is used to configure most of the LVGL configuration options via menuconfig, so it's not necessary to use a custom lv_conf.h file.

It is recommended to add LVGL as a submodule in your IDF project's git repo.

From your project's root directory:

1. Create a directory named components (if you don't have one already) with mkdir -p components.
2. Clone the lvgl repository inside the components directory with git submodule add https://github.com/lvgl/lvgl.git components/lvgl
3. Run idf.py menuconfig, go to Component config then LVGL configuration to configure LVGL.

Use lvgl_esp32_drivers in your project

It is recommended to add lvgl_esp32_drivers as a submodule in your IDF project's git repo.

From your project's root directory:

1. Create a directory named components (if you don't have one already) with mkdir -p components.
2. Clone the lvgl_esp32_drivers repository inside the components directory with git submodule add https://github.com/lvgl/lvgl_esp32_drivers.git components/lvgl_esp32_drivers
3. Run idf.py menuconfig, go to Component config then LVGL TFT configuration and LVGL TFT Display configuration to configure lvgl_esp32_drivers.

Platformio support

Using the lv_platformio project add the following lines to platformio.ini file:

[env:esp32]
platform = espressif32
framework = espidf
board = esp-wrover-kit

Change the default environment to default_envs = esp32.

Modify the main.c like this:

#include "lvgl.h"

// #include "driver.h"

#include "demo.h"

int app_main(void)
{
    lv_init();

    /* Initialize your hardware. */
    
    /* hw_init(); */

    demo_create();

    /* Create the UI or start a task for it.
     * In the end, don't forget to call `lv_task_handler` in a loop. */

    /* hw_loop(); */

    return 0;
}

For more information see: platformio with espidf framework compability.

ESP32-S2 Support

Support for ESP32-S2 variant is Work In Progress. Smaller displays (e.g. 320x240) work fine, but larger ones need testing.

Background

ESP32-S2 has less on-chip SRAM than its predecessor ESP32 (520kB vs. 320kB). This causes problems with memory allocation with large LVGL display buffers as they don't fit into the on-chip memory and external PSRAM is not accessible by DMA.

Moreover, static allocation to external PSRAM is not yet supported (see GitHub issue).

At this momement, the buffers are dynamicaly allocated with DMA capabilty and memory allocator handles the rest.

Documentation references

Display interface to read about how we use the callbacks to draw in displays that are not natively supported by LVGL

Input drivers (touch)