Developing User Interfaces for ESP-Based Custom-Made Dev Boards

Shanghai, China
Nov 2, 2022

This article explains how you can use SquareLine Studio for developing UIs on custom-made boards with LCDs, which are based on an Espressif MCU.

A few weeks ago, we discussed how SquareLine Studio can be used for developing impressive user interfaces on Espressif boards. In this article, we’ll shift our attention to how you can use SquareLine Studio with custom-made boards and LCDs, which are based on an Espressif MCU.

First off, you need to start with the custom_waveshare_7inch example from the ESP-BSP repository on GitHub, which is based on the same code as other Espressif examples of using SquareLine Studio. However, in this case there must be a custom-made component that is similar to Espressif’s Board Support Package (BSP), whose main functions are about handling the LCD screen and initializing the LVGL graphic library. So, for this particular example we have selected the following LCD: WaveShare 7inch 800x480 with an RA8875 graphical controller and a GT911 touch screen controller.

1. Customizing Your Board Support Package (BSP)

Developing packages on SquareLine Studio requires of you to make a component that is similar to BSP. You can refer to the example we developed on GitHub, based on a 7inch WaveShare LCD. It should be noted that only the most important functions are implemented in the ws_7inch.c file. If you want to adapt to another screen model, you need to modify the following functions:

If the communication with the touch screen is not based on an I2C interface, you should initialize the SPI or another communication interface, as shown below:

The second step in customizing the BSP is to edit the ws_7inch.h header file, which defines all the pin configurations, communication rates and screen sizes of the development board.

Finally, if you want to modify the file name or add new dependencies to the LCD and touch screen, you need to update CMakeLists.txt and idf_component.yml. After modifying the component name, you also need to update idf_component.yml in the main program.

2. Board Description File and Image

After the BSP is fully customized, we can update the board description file manifest.json:

The name, version, mcu, short_description and long_description can be set to any value, since they are meant only for displaying your board correctly on SquareLine Studio. Values, such as screen_width, screen_height and screen_color_swap, are more important, since they define the physical parameters of your LCD. The placeholders should be updated with the right values from your customized BSP; likewise, the header file path should change to __ESP_BOARD_INCLUDE__ and the touch screen initialization function to __ESP_BOARD_I2C_INIT__.

The second file to be updated is the board image image.png, whose size should be 380px x 300px.

3. ESP-IDF and LVGL Default Configuration

If you have any special settings for the ESP-IDF or LVGL configuration, you can put them into the sdkconfig.defaults file. Moreover, the configuration option CONFIG_LV_COLOR_16_SWAP must be the same as the screen_color_swap in the manifest.json file.

4. Generate a Package and Copy It to SquareLine Studio

After updating all the files, you can run the generator in the SquareLine folder, in order to generate a package:

When the package is generated, it will be placed in the espressif file in the output_folder. Finally, copy the generated package, that is, espressif/custom_waveshare_7inch, into the boards folder in the SquareLine Studio Installation directory.

5. Launching SquareLine Studio

After launching SquareLine Studio, you should be able to see your customized board in the Create tab and the Espressif tab, along with your board’s name, description and image.


You can now create your own project with your customized board and use various LVGL widgets along the way. We recommend that you avoid using zoomed-in images, as this may slow down the overall operation, while larger images will take up much of the microcontroller’s flash memory. Instead of this, you can resize images in another image editor and then use them in full size.

After the project is completed, you can export the template by selecting Export -> Create Template Project in the main menu, and similarly you can export the UI file by selecting Export -> Export UI Files in the main menu.

Finally, build and flash the file, with the following command:

Last, but not least, when using larger images, please do not forget to modify the factory partition size in the partitions.csv file, and also modify the flash size of the selected module in menuconfig. Otherwise, you may end up building too big an application which will consequently reduce the space that is necessary for downloading it.

Share this article
Reuse this content


Technical Writer and Editor

About this author ›