esp32_smartdisplay: LVGL drivers for the Sunton CYD boards

The problem: every CYD board needed its own display and touch setup

The boards this library targets are the Sunton smart display boards, sold as the Cheap Yellow Display, and the description says it plainly: this is a PlatformIO library of LVGL drivers for them that supports these boards without any effort.

The starting point matters. These boards arrive with an ESP32 and an LCD, and most of them with a touch interface, and the common experience described in the README is that the vendor link and the bundled examples look fine to someone who already knows the ecosystem. The awkward part comes later, when the display library, the touch driver and the board definition have to agree with each other.

The author lists the specific problems encountered with the general purpose display libraries, and the list is a design brief for this one: lots of configuring before it works, unnecessary code included for other boards, no support for rotating on the fly, no support for touch, not reusing code already present in the ESP firmware, no LVGL integration, and no easy way to compile the same application for different boards.

Read as a whole, the pitch is not faster code but less configuration and a single application that can be built for several boards. The audience is a hobbyist or engineer who bought a display board, wants a working LVGL interface on it, and does not want to become an expert in the display driver's configuration files.

The supported board list is explicit, and the suffix tells you the touch type

Coverage is the first thing to check, and the README is specific. The boards have an LCD display and most of them have a touch interface. The naming convention is explained directly: N stands for no touch, R for resistive touch and C for capacitive touch. The list currently covered runs from the small ESP32-1732S019 in N and C, through the 2424S012 and 2432S022, the 2432S024 in R, C and N, the 2432S028 in R with three variants, the 2432S032 in N, R and C, the 3248S035 in R and C, the 4827S043 in R and C, the 4848S040C_I_Y_1/3, and up to the 8048S050 and 8048S070 in N, C and R.

That list is a compatibility contract rather than a marketing claim, and the repository backs it up with structure: there is a boards directory, a BOARD_MATRIX.md file at the root, and a platformio.ini in the project. The board matrix is the file to read before buying anything, because a display that is not on the list means an unsupported build, not a small configuration difference.

The repository also carries a library.json, which is what lets the library be pulled by name from the PlatformIO registry, an include directory, a src directory, a test directory and a .gitmodules file, which matters because the clone step in the quick start uses submodules.

One more detail: the display chips in play are named in the repository topic tags, with ili9341 and st7796, and the touch controllers with xpt2046, so you can check the hardware on the board against what the library expects.

Two dependencies, and one of them supplies the board definitions

The dependency list is short. The library depends on LVGL, currently version 9.1.0, and on platformio-espressif32-sunton, the board definition package that also holds the data sheets, ordering information and details for the Sunton boards.

That second dependency is the one that removes the configuration work. The display driver story in the wider LVGL ecosystem usually involves picking a board file, matching the pins, the chip and the touch controller, and editing a configuration file. Supplying the board definitions alongside the drivers means the same application can be compiled for different boards, which is the last item on the author's list of what the general purpose libraries could not do.

The library also states something about its own future. It uses the newly introduced esp_lcd_panel interfaces, and the note says this should provide some support in the future for updates and new boards, and that these drivers are provided by Espressif and have already been copied and included into this library.

That last clause is worth pausing on. The panel drivers are vendored copies rather than a live dependency, which means the library can keep working against an older ESP-IDF, and it also means upstream fixes to those drivers do not arrive automatically. The trade is stability of the build against freshness of the low level code.

The library is published on the PlatformIO registry under the name rzeldent/esp32_smartdisplay, and the homepage for the board information is a separate repository, platformio-espressif32-sunton.

From clone to running interface in five steps

The quick start is five steps, and the detailed guide expands them into nine. Step one is getting the code, and the submodules matter here.

git clone --recurse-submodules <repo>

Step two and three are PlatformIO work: open PlatformIO, add the board definition, create a new project, and then add the library to the project by listing it in the project configuration.

lib_deps = rzeldent/esp32_smartdisplay

Step four is a call to the initialisation function in the setup function of your sketch.

smartdisplay_init()

Step five is the part that trips up newcomers, and the README flags it in the quick start as well as in the detailed steps: you have to update the tick in the loop function. LVGL is not driven by an internal timer, so the application has to call the LVGL tick handler on a schedule for the display to refresh and the input to be read. The library provides the initialisation that wires the display, the touch and the LVGL port together, but the tick remains the application's job.

Step six is copying the build flags from the documentation into the project, and step five of the detailed guide is creating a settings file for LVGL, that is the lv_conf.h file, which LVGL requires to be configured before it compiles. Step eight is optional and covers generating a user interface with SquareLine Studio, and step nine is compiling, uploading and watching the screen work.

The API covers backlight, adaptive brightness, the RGB LED and touch calibration

The documented entry points are listed explicitly in the README, and they are the parts of a display board that usually need hand-written code. There is the initialisation function, a backlight setter that takes a float duty cycle, a brightness callback registration that takes a callback and an interval, and an RGB LED setter with three booleans for the red, green and blue channels.

The backlight setter is called with a float duty cycle, and the RGB LED setter takes three booleans, one per colour channel.

The backlight and the RGB LED are the parts of these boards that are most often wired up by hand in a vendor example, and having them as library calls with named semantics is what removes a chunk of boilerplate.

Touch is handled with a calibration data type and a function that computes it from three screen points and three touch points.

Three points is a small sample, and the type name suggests the result is stored rather than applied on the fly, which is the right shape for a resistive panel where the calibration depends on the exact screen and the touch overlay.

The documentation also has a section on rotation of the display and touch, which addresses directly the on the fly rotating item from the list of gaps in the general purpose libraries. A separate appendix provides a template to support all the boards, and another covers the external dependencies.

Porting from LVGL 8.3.9 touches the config file and the ticker

The README keeps a dedicated section for porting from LVGL 8.3.9, which tells you two things about the migration. The first is that the lv_conf.h settings file has to be revisited, since the configuration options between LVGL 8 and LVGL 9 are not the same. The second is the ticker, the same tick update that the quick start asks for, which is the piece of LVGL integration that changes most between versions.

That this is called out as its own section is a sign of how the audience actually uses the library. Most people arrive at a Sunton board from a tutorial that used TFT_eSPI or LovyanGFX and LVGL 8, and the mechanical part, the display and touch drivers, is handled for them. What is left is the LVGL version change, which is the part that actually touches their code.

There is also a demo application linked from the README, esp32-smartdisplay-demo, which the README recommends looking at to see what the library can do. The demo is described as providing a user interface created with the SquareLine Studio GUI generator, reading the CdS light sensor, control of the LEDs, and support for all known boards.

The combination of a demo application, a board matrix and a template appendix means the library is aimed at people who will read code, not only people who will copy a snippet. That is a reasonable expectation for hardware libraries, and it is also a fair description of the support effort involved.

GPL-3.0, a release that stopped in 2024 and commits that did not

The licence is GPL-3.0, and it is stated plainly in the repository metadata. For a library that is compiled into firmware, that matters more than it does for a script: distributing a product that contains GPL-3.0 code carries obligations, and a team shipping a closed device has to settle how it handles those obligations. That is a compliance question for your own legal process, not something the README addresses, and the fact that the licence is unambiguous is better than the alternative.

The release history is the more surprising part. The tagged releases are 2.1.0 on 2024-11-16, 2.0.11 on 2024-08-27 and 2.0.10 on 2024-07-07, so the last tagged release is from 2024. The last push to the repository was on 2026-10-02, and the repository is not archived. The commits continue, the tags do not.

For a PlatformIO library that matters mostly in one place. The PlatformIO registry resolves a dependency by version, so pinning rzeldent/esp32_smartdisplay to a tagged release gives you 2.1.0 and nothing newer, while tracking the main branch gives you current code with no version marker to point at. A project that wants reproducibility has to decide which of the two it values more.

The library sits in the PlatformIO registry, and the board definitions live in a separate repository, so a project depends on two moving parts rather than one. The last commit badge and the CI workflow badge in the README are the only signals available about how much care a given commit has received, and for a project without releases those signals carry more weight than usual.

Editorial conclusion

Adopt esp32_smartdisplay when your project uses one of the listed Sunton ESP32 display boards and you want LVGL 9 with touch and rotation support in one library instead of stitching a display driver, a touch driver and a vendor example board file together. Do not adopt it if you need a released, tagged version of your stack, since the last release was 2.1.0 on 2024-11-16 while the last push was on 2026-10-02, so you would be pinning to a commit. Before you commit hardware to it, check two things: that your exact board suffix is in the supported list, where N means no touch, R resistive and C capacitive, and that your firmware distribution plan can live with GPL-3.0, because the licence covers the library and linking it into a product raises obligations you have to settle yourselves.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. rzeldent/esp32-smartdisplay on GitHub