LVGL (Light and Versatile Embedded Graphics Library ) example project for Espressif IDF (IoT Development Framework) version 5.2. That can be used in combination with SquareLine Studio (GUI based user interface design program) for generating firmware for ESP32 based boards.
Big thanks to Hiruna, I forked his project and implemented minor changes to make it work with the Sunton ESP32-2432S028 board
Clone this repo:
git clone --recurse-submodules https://github.com/littleboot/lv_port_esp32_squareline_studio.git
Copy the boards\sunton_esp32_2432S028
board folder to the SquareLine Studio boards folder, the SquareLine Studio docs stated that this location can be found inside the installation directory however on my windows system this folder was located inside documents folder: C:\Users\admin\Documents\SquareLine\boards\Espressif
.
Open SquareLine Studio and create a new project for the Sunton ESP32-2432S028 board. Choose a project name and location for the project.
Configure the "Project export root" path to a folder were you would like to have the IDF project.
Design a GUI (you can also do this later, a empty gui is sufficient) and export the idf project template and UI files.
NOTE: after every UI Files export you need to run the fix script to fix the CMakeLists.txt file
Tip:
You can also add a task to the VScode project folder that runs the script:
Add this task to the tasks.json
file located in the .vscode
folder inside the project directory.
{
"label": "Squareline UI export fix CMakeLists file",
"type": "shell",
"command": "powershell",
"args": [
"-NoProfile",
"-Command",
"cd \"${workspaceFolder}/components/ui\" ; ./fix_CMakeLists_file.ps1"
],
"problemMatcher": []
},
To run the task press F1:
click on the task:
You should now be able to compile the project with IDF V5.2.
I prefer using VScode in combination with the ESP-IDF extension. However the project can be used with other IDE's as wel.
To be able to compile and flash the device from within vscode using the ESP_IDF extension it needs to know where it can find the idf build tools. These settings are stored in the project root .vscode
folder.
To generate this folder:
- open vscode, Install and configure the ESP-IDF extension
- Create new idf project (press f1, and run cmd:
ESP-IDF: New Project
) - Configure this project and when finished copy the
.vscode
folder to the folder were the board template project was exported by SquareLine Studio. - Open the SquareLine Studio exported template folder in vscode (as root directory).
- Build and flash the project to test if it is working.
A very simple UI was created in SquareLine Studio (V1.3.4) to validate the hardware:
To use this UI copy the exported UI files from \examples\sunton_esp32_2432S028\simple_ui_export\ui
to the idf project folder __ui_project_name__\components\ui
or export them yourself using SquareLine Studio, the project files are located here: \examples\sunton_esp32_2432S028\simple_ui_squareline_project
NOTE: You will have to change the Project Export Root
UI Files Export Path
inside the project settings
Like a lot of my projects this one started with a purchase on AliExpress. I was looking for a cheap development board with a display that I could use to read and show sensor values for a proof of concept design I'm working on.
That's when I found the following board:
Sunton ESP32-2432S028 (โฌ14,16 inc shipping Order date: Dec 14, 2023) AliExpress link
It seemed like a perfect fit and I taught I should have it working quickly. However this turned out to be a bit of a challenge.
- The official LVGL example port for the ESP32 (lv_port_esp32) couldn't be compiled with the latest stable version of IDF 5.2 as of writing (06/02/2024)
- Backlight / brightness setting not working
- LVGL demo was displayed incorrectly: wrong orientation, inverted and incorrect colors
- Compiling project with UI export from SquareLine Studio
After trying to fix the lv_port myself, I found a working project of someone that recently created a lvgl port for the sunton_esp32_2432S028 that could be compiled with IDF 5.2: https://github.com/limpens/esp32-2432S028
This worked but I actually wanted a working project based on the official port because I'm planning to use a different display and controller for future projects. After looking at the official repo again I finally noticed the pull request and found the https://github.com/hiruna/lv_port_esp32/tree/develop/lvgl_8.3.7_idf_5.2 repo!
Thank you hiruna! He fixed the official port, he even made a pull request. I have no clue why it is still not merged with the official repo. Noticing this sooner could have saved me a lot of time.
After configuring the project menuconfig (idf sdk config) so the correct GPIO's were assigned to the driver. (The pinout can be found here: https://macsbug.wordpress.com/2022/08/17/esp32-2432s028/)
LCD Signal | ESP32-2432S028 |
---|---|
RESET | - |
SCL (CLK) | GPIO14 |
D/C (RS) | GPIO2 |
CS | GPIO15 |
SDA (MISO) | GPIO12 |
SDO (MOSI) | GPIO13 |
Backlight | GPIO21 |
I noticed that the backlight (and changing the brightness level) was not working. As a quick workaround I changed the backlight control method from PWM to SWITCH control in the sdk config: CONFIG_LV_DISP_BACKLIGHT_SWITCH=y
.
TODO, implement proper fix for this bug. See: lvgl/lvgl_esp32_drivers#222 (zuckschwerdt reply)
When I first uploaded one of the demo UI's to the board, the display was inverted and the colors were incorrect (orange color instead of blue):
This problem was caused by an incorrect data buffer definition in the ili9341_set_orientation
function:
This buffer describes the initialization state of the Memory Access Control register of the display driver. For more information see datasheet ili9341 driver page 129 "8.2.29. Memory Access Control (36h)".
For the Sunton ESP32-2432S028 board it should be defined as:
uint8_t data[] = {0x60, 0x20, 0x00, 0x80};
The correct definition can differ between boards, this can be found by trial and error. The code below can be added to overwrite the data buffer to try out different bit values:
//Memory Access Control register (36h)
uint8_t MAC_reg = 0x00;
//Register Bit values
//These 3 bits control MCU to memory write/read direction.
uint8_t MY_RowAddressOrder = 0; //D7
uint8_t MX_ColumnAddressOrder = 1; //D6
uint8_t MV_RowColumnExchange = 1; //D5
//LCD vertical refresh direction control.
uint8_t ML_VerticalRefreshOrder = 0; //D4
//Color selector switch control (0=RGB color filter panel, 1=BGR color filter panel)
uint8_t BGR_RGBBGROrder = 0; //D3
//LCD horizontal refreshing direction control.
uint8_t MH_HorizontalRefreshOrder = 0; //D2
//D1 = Don't care
//D0 = Don't care
MAC_reg |= (MY_RowAddressOrder << 7);
MAC_reg |= (MX_ColumnAddressOrder << 6);
MAC_reg |= (MV_RowColumnExchange << 5);
MAC_reg |= (ML_VerticalRefreshOrder << 4);
MAC_reg |= (BGR_RGBBGROrder << 3);
MAC_reg |= (MH_HorizontalRefreshOrder << 2);
ESP_LOGI(TAG, "MAC_reg value: 0x%02X", MAC_reg);
data[orientation] = MAC_reg;
After every export of the UI files from SquareLine Studio the CMakeLists.txt file needs to be fixed:
.\__ui_project_name__\components\ui\fix_CMakeLists_file.ps1
for windows.\__ui_project_name__\components\ui\fix_CMakeLists_file.ps1
for linux
This will replace the add_library
function in the CMakeLists.txt
with the idf specific version idf_component_register
.
Additionally the ui_events.c
wasn't generated by SquareLine Studio making the compilation fail. To fix this an empty c file with this name was added to the UI folder.
The esp32 driver repo was forked and updated to include the Sunton ESP32-2432S028 for automatic configuration (by modifying the kconfig and ili9341 driver files).
This repository can be used to generate SquareLine Studio boards for ESP32 devices (connected to supported display drivers defined in lvgl_esp32_drivers).
Project structure in _ui_project_name_ follows a similar structure to lv_port_esp32.
- ESP-IDF
- v5.2 master
lvgl_esp32_drivers
- LVGL
Board Name | Driver | Image | Example |
---|---|---|---|
esp32_ssd1306_128x64 | SSD1306 | ![]() |
![]() Source Files |
Refer to https://docs.squareline.io/docs/obp.
- Clone this repo
- Create a new directory under boards/
- Example:
your_board_name/
- Example:
- Add the
your_board_name.png
file- A photo of the board to be displayed in SquareLine Studio.
- Add the
your_board_name.slb
- SquareLine board definition file (see https://docs.squareline.io/docs/obp#your_boardslb for more information)
- For monochrome displays such as the SSD1306 OLED panel, keep the
color_depth
at8
, SquareLine currently does not support depth < 8. You will need to fix this, see below. - Set the
lvgl_export_path
tofalse
as the submodule reference _ui_project_name_/components/lvgl is used - Set the
pattern_match_files
toCMakeLists.txt,main/main.c
as this will replace templated tags such as__UI_PROJECT_NAME__
- Set the
ui_export_path
to./components/ui
- Set the
supported_lvgl_version
to8.3.*
- For monochrome displays such as the SSD1306 OLED panel, keep the
- SquareLine board definition file (see https://docs.squareline.io/docs/obp#your_boardslb for more information)
- Copy
your_board_name/
directory to the SquareLine installation'sboards/Espressif
directory - Create a compressed ZIP file of the _ui_project_name_ directory
- This is common to all supported display drivers in lvgl_esp32_drivers
- Rename the ZIP file to
your_board_name.zip
- Copy the
your_board_name.zip
to SquareLine installation'sboards/Espressif/your_board_name
directory
- Once you have created a new board (or used one of the existing boards in this repo), open SquareLine Studio.
- The board you've created will appear in SquareLine Studio.
-
Example of the ESP32 SSD1306 128x64 OLED "board" is shown below.
-
- Set your project settings and create the project
- Once the new project is created and loaded, export the template project via Export -> Create Template Project
- Open the exported template project directory via your IDE. I am using CLion to open it.
- Once the project is opened via the IDE, CMake will throw the following error:
- Run
idf.py menuconfig
to configure the display drivers and LVGL - Build the ESP-IDF project
- Flash the ESP32 board
As previously mentioned, SquareLine Studio currently does not support color depth < 8. Assuming that you've set the
LVGL color depth to 1
via the project's menuconfig
, build attempts will result in the following error:
- This error is the result of an automatically added assertion/config check, in the generated UI files. It checks if
the set
LV_COLOR_DEPTH
(i.e set viamenuconfig
) matches thecolor_depth
set in the board's.slb
file. - To fix this error, simply replace the expected color depth (i.e.
8
) to1
- Building the project after fixing this error will succeed
- This error is the result of an automatically added assertion/config check, in the generated UI files. It checks if
the set
Assuming that you've only enabled the "Monochrome theme" for your monochrome display (as you should via the project configuration
i.e.menuconfig
)
- Example
This happens because SquareLine Studio currently does not include an option to select the monochrome theme.
To fix this issue, simply change the theme initialization code as follows:
- NOTE: You will need to modify this every time you export the UI files.