ESPHome + LVGL on cheap touchscreen devices

Supported Devices

• Guition JC3248W535 3.5" with capacitive touch and USB-C. AliExpress Link.
• Sunton ESP32-2432S028R 2.8" with resistive touch and USB micro-B. AliExpress Link.
• Sunton ESP32-8048S043 4.3" with capactivive touch and USB-C. AliExpress Link.
• Sunton ESP32-8048S050 5.0" with capactivive touch and USB-C. AliExpress Link.
• Elecrow CrowPanel DIS05035H (v2.2) 3.5" with resistive touch and USB-C. Manufacturer's Link.

Changelog

2024-11-06

• Update common.yaml to require ESPHome min version 2024.11.0 (currently in dev) due to upcoming changes to some display and touch drivers, and to add support for the Guition device which uses drivers not supported on the stable release as of yet.
• Update Sunton ESP32-8048S043 and ESP32-8048S050 configs to support upcoming ESPHome changes that affect display & touch rotation.
• Add support for Guition JC3248W535 3.5" device.
• Tweak devce configs so that majority of sections are in list format rather than a mix of formats.
• Fix touchscreen configs for devices with resistive touch on newer ESPHome builds.

2024-11-01

• [Breaking change] Moved device_name and friendly_name from substitutions: to esphome: at the top-level. This allows for ESPHome's Rename Hostname feature to work again.
• Added an id to each device's display: and touchscreen: config to allow extending them more easily (for example, if you want to rotate a display / touchscreen from the top-level config for a specific device).

File Structure

If all you are looking for is a device-specific config then look no further than the devices/ directory. The YAML files in there are clean and free from anything not related to the devices themselves. They are intended to be used as Packages in a higher-level YAML config file, which allows for device-specific settings and common settings to be kept in separate files, avoiding duplicate code and making it easier to update groups of devices.

The YAML files in the root of this repo demonstrate how to use each device's config file with a common config, as well as a resolution-specific (but not device-specific) LVGL config/layout.

Advanced YAML Techniques

Aside from the Packages feature used to separate device-specfic YAML from common YAML config, there are some other potentially unfamiliar techniques in use here. For example, the files within layouts/ use YAML anchors and aliases which help reduce code duplication. I use anchors and aliases instead of style_definitions and styles as anchors can be used on anything instead of being restricted to just styles, and because they override theme settings when used (there is a bug or perhaps odd design choice that prevent styles from overriding theme). I define most of my anchors within a made-up section called .sizing because top-level sections prefixed with a period do not cause errors when parsed by ESPHome.

How-tos

How to specify the home page on a particular device

To change which page loads at boot time and when the home button is pressed on a particular device, adjust the home_page variable in the device's config file to the ID of the desired page.

For example, to set a page with the ID printers, adjust this in your device's config file:

substitutions:
  ...
  home_page: printers

How to hide pages on particular devices

To hide a page on a particular device, extend the desired page definition by adding skip: true using !extend (see Packages feature).

For example, to hide a page with the ID bedroom, add this to your device's config file:

lvgl:
  pages:
    - id: !extend bedroom
      skip: true

Todo

This readme isn't finished. I'll be elaborating on some more techniques being used in here, such as the modularization of the widgets using !include and how the stateful widget files relate to their sensor counterparts (tip, just make sure to pass the same uid and entity_id when including a widget and when including the related widget sensor).

Photos

These look better in real life, I promise! I took these photos in low-light and displays are not easy to photograph in general.

4.3" 800x480 (Sunton ESP32-8048S043)

3.5" 480x320 (Guition JC3248W535)

3.5" 480x320 (Elecrow DIS05035H)

2.8" 320x240 (Sunton ESP32-2432S028R)