Skip to content

Latest commit

 

History

History
124 lines (86 loc) · 9.02 KB

how_to_use.md

File metadata and controls

124 lines (86 loc) · 9.02 KB

How to Use

Table of Contents

Dependencies

Dependency Version
lvgl >= 8.3 && < 9

Based on ESP-IDF

Adding to Project

esp-ui has been uploaded to the Espressif Component Registry, and users can add it to their project using the idf.py add-dependency command, for example:

idf.py add-dependency "espressif/esp-ui"

Alternatively, users can create or modify the idf_component.yml file in the project directory. For more details, please refer to the Espressif Documentation - IDF Component Manager.

Configuration Instructions

When developing with esp-idf, users can configure esp-ui through the menuconfig:

  1. Run the command idf.py menuconfig.
  2. Navigate to Component config > ESP-UI Configurations.

Project Examples

Here are examples of using esp-ui on the esp-idf development platform:

Based on Arduino

Installing the Library

For online installation, navigate to Sketch > Include Library > Manage Libraries... in the Arduino IDE, then search for esp-ui and click the Install button.

For manual installation, download the required version of the .zip file from esp-ui, then in the Arduino IDE, navigate to Sketch > Include Library > Add .ZIP Library..., select the downloaded .zip file, and click Open to install.

Users can also refer to the Arduino IDE v1.x.x or Arduino IDE v2.x.x documentation for library installation guidelines.

Configuration Instructions

When developing with Arduino, users can configure esp-ui by modifying the first esp_ui_conf.h file found in the search path, with the following features:

  1. esp-ui searches for configuration files in the following order: current project directory > Arduino library directory > esp-ui directory.
  2. All example projects in esp-ui include a configuration file by default, which users can modify directly. If you want to use a configuration file from a different path, delete the one in the project.
  3. For projects without a configuration file, users can copy it from the root directory of esp-ui or from example projects into their own project.
  4. If multiple projects need to use the same configuration, users can place the configuration file in the Arduino library directory, allowing all projects to share the same configuration.

Note

  • Users can find and modify the path of the Arduino library directory by selecting File > Preferences > Settings > Sketchbook location in the Arduino IDE menu.

Warning

  • Due to potential desynchronization between configuration file updates and esp-ui version updates, the library manages its version independently and checks whether the user's current configuration file is compatible with the library during compilation. Detailed version information and checking rules can be found at the end of the esp_ui_conf.h file.

Here is an example of enabling LOG debugging by modifying the esp_ui_conf.h file:

...
/**
 * Log level. Higher levels produce less log output. Choose one of the following:
 *      - ESP_UI_LOG_LEVEL_DEBUG: Output all logs (most verbose)
 *      - ESP_UI_LOG_LEVEL_INFO:  Output info, warnings, and errors
 *      - ESP_UI_LOG_LEVEL_WARN:  Output warnings and errors
 *      - ESP_UI_LOG_LEVEL_ERROR: Output only errors
 *      - ESP_UI_LOG_LEVEL_NONE:  No log output (least verbose)
 *
 */
#define ESP_UI_LOG_LEVEL        (ESP_UI_LOG_LEVEL_DEBUG)
...

Project Examples

Users can access them by navigating to File > Examples > esp-ui in the Arduino IDE. If the esp-ui option is not available, check if the library is installed correctly and ensure that an ESP board is selected.

Here are examples of using esp-ui on the Arduino development platform:

App Examples

esp-ui provides general app examples for the following system UIs. Users can modify these examples based on their actual needs to quickly develop custom apps.

  • Phone
    • Simple Conf: This example uses a simple app configuration with most parameters set to default values, requiring only a few necessary parameters to be configured by the user. It is suitable for GUI development using "handwritten code"[Note 1].
    • Complex Conf: This example uses a complex app configuration where all parameters need to be configured by the user. It is suitable for GUI development using "handwritten code"[Note 1].
    • Squareline: This example uses a simple app configuration with most parameters set to default values, requiring only a few necessary parameters to be configured by the user. It is suitable for GUI development using "Squareline exported code"[Note 2].

Note

  1. "Handwritten code" refers to manually writing code to implement the GUI, usually using lv_scr_act() to get the current screen object and adding all GUI elements to this screen object.
  2. "Squareline exported code" refers to using Squareline Studio to design the GUI, exporting the code, and then adding the exported code to the app to implement the GUI.
  3. The app provides an automatic resource cleanup function (enable_recycle_resource), which automatically cleans up resources such as screens, animations, and timers when the app exits. This function requires all resources to be created in the run() function; otherwise, memory leaks may occur. If you need to create resources outside the run() function, disable this function and redefine the cleanResource() function to implement manual cleanup.
  4. The app provides an automatic default screen creation function (enable_default_screen), which automatically creates and loads a default screen when the app runs. Users can obtain the current screen object through lv_scr_act(). If you need to create and load the screen object manually, disable this function.

Warning

  • When using the "handwritten code" method in the app, to avoid variable and function name conflicts between multiple apps, it is recommended that global variables and functions in the app use the "<app_name>_" prefix.

Warning

  • When using the "Squareline exported code" method in the app, it is recommended to use Squareline Studio version v1.4.0 or above.
  • It is strongly recommended not to use animations in Squareline, as these animation objects cannot be accessed by the user or esp-ui, and therefore cannot be cleaned up automatically or manually, potentially leading to crashes or memory leaks when the app exits.
  • To avoid variable and function name conflicts between multiple apps, it is recommended to name all screens with the "<app_name>_" prefix and set "Project Settings" > "Properties" > "Object Naming" to "[Screen_Widget]_Name" in Squareline Studio (this feature requires version >= v1.4.0).
  • Since each set of Squareline exported code includes ui_helpers.c and ui_helpers.h files, to avoid function name conflicts between multiple apps, delete these two files and use the ui_helpers files provided internally by esp-ui. After deletion, modify the #include "ui_helpers.h" in the ui.h file to #include "esp_ui.h".