Lesson02_CrowPanel_Display_LVGL: Basic Display on a 240×240 Round Screen¶

1. Course Introduction¶

This lesson uses ESPHome 2026.7.4 and ESPHome Device Builder 1.9.2 to configure the CrowPanel 1.28inch-HMI ESP32 Rotary Display. After the program starts, it turns on the backlight and onboard power output, drives the GC9A01A 240×240 round LCD via SPI, and finally LVGL creates a white page and displays Hello World! in the center.

Learners need to add the YAML to ESPHome, configure their private Wi-Fi parameters, complete validation and flashing, and observe the screen and startup logs. This lesson is the foundation for the subsequent rotary dimming and LVGL gauge interface lessons: only when the display chain in this lesson works properly can you proceed to evaluate the subsequent UI and input functions.

2. Learning Objectives¶

Be able to explain the CrowPanel startup sequence from power output, SPI bus, LCD initialization, to LVGL rendering.
Be able to import, validate, and install the YAML configuration in ESPHome Device Builder 1.9.2.
Be able to identify the impact of the GC9A01A driver, SPI pins, color inversion, and screen orientation on the display result.
Be able to determine whether the basic display experiment is successful based on the backlight, the Hello World! page, and the serial logs.

3. Preparation¶

One CrowPanel 1.28inch-HMI ESP32 Rotary Display.
One USB data cable compatible with the rotary screen's data transfer.
ESPHome Device Builder 1.9.2.
ESPHome 2026.7.4.
Available 2.4 GHz Wi-Fi.

Code download link: Elecrow Official Lesson_Code

4. Software Operation Steps¶

Open ESPHome Device Builder 1.9.2 and confirm that its ESPHome Core version is displayed as 2026.7.4. If the versions do not match, perform the upgrade or switch the environment first to avoid component syntax differences.
Create a new project, place rotary-screen-128-display.yaml into the ESPHome configuration directory, and open the corresponding configuration in the device list. However, device names within the same network must not be duplicated.

A. Click Create device to create a new project.

B. Select the esp32s3 main controller.

C. Name the project. Complete the creation task.

Copy the official code into the project (the code is provided above).

However, make sure the project name in this code matches the name of the project you just created.

Modify the Wi-Fi.

Click the three dots in the upper-right corner, then click Secrets.

You can enter your own Wi-Fi name and password. (Make sure this Wi-Fi is on the same local network as your Home Assistant system.)

Click Install, select the USB installation method suitable for the current environment, choose the serial port corresponding to the CrowPanel, and complete compilation and flashing. After flashing finishes, open the log window and you should see the device startup and POWER ON log.

Wait for compilation.

After compilation completes, click Flash to upload.

Select the connected serial port.

Click to connect to the corresponding serial port (confirm that the hardware is already connected).

Wait for the download to complete.

5. Hardware Operation Steps¶

With the device powered off, check that the screen, rotary encoder housing, and USB connector show no obvious damage, then use a USB cable that supports data transfer to connect the CrowPanel 1.28inch-HMI ESP32 Rotary Display to the computer.

Wait for the LVGL page to be built, then look directly at the center of the round screen. The screen should display a white background and black Hello World!, with the text fully visible, centered, and without obvious misalignment or display corruption.

6. Key Code Explanation¶

6.1 Project and External Memory Configuration¶

esphome:
  name: rotary-screen-128-display
  friendly_name: Rotary_Screen_1.28_Display
  platformio_options:
    build_flags: "-DBOARD_HAS_PSRAM"
    board_build.esp-idf.memory_type: qio_opi
    board_build.flash_mode: dio

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf
    version: recommended

psram:
  mode: octal
  speed: 80MHz

name is the device's unique identifier, and friendly_name is the display name shown in the interface. The project uses the ESP32-S3 DevKitC as the compilation target and uses the recommended version of ESP-IDF. The three PlatformIO parameters are responsible for enabling PSRAM, specifying the QIO/OPI memory interface, and the DIO Flash mode; at runtime, the PSRAM is then set to 80 MHz Octal mode. LVGL buffers, fonts, and widgets require external memory, and if these parameters do not match, startup failure, repeated resets, or memory allocation failure may occur.

6.2 Turning On the Backlight and Onboard Output at Startup¶

on_boot:
  priority: 800
  then:
    - logger.log: "Backlight ON"
    - output.turn_on: gpio_3_backlight_pwm
    - delay: 200ms
    - output.turn_off: power_light
    - output.turn_on: out1
    - output.turn_on: out2

This automation corresponds exactly to the code in this lesson. At startup, it first logs Backlight ON, turns on the backlight PWM on GPIO46, waits 200 ms, then turns off the corresponding output on GPIO40, and turns on GPIO1 and GPIO2. The delay provides stabilization time for the onboard power and display components. If the log is normal but the screen is completely black, you should check the GPIO46 backlight output and the SPI display chain separately.

6.3 ESP32-S3 and PSRAM Settings¶

esp32:
  board: esp32-s3-devkitc-1
  framework:
    type: esp-idf
    version: recommended

psram:
  mode: octal
  speed: 80MHz

The project defines the ESP32-S3 DevKitC as the compilation target, uses the recommended version of ESP-IDF, and sets the PSRAM to 80 MHz Octal mode. The BOARD_HAS_PSRAM and qio_opi build parameters at the top of the YAML are also used to enable external memory. If the configuration does not match, startup failure, repeated resets, or LVGL memory allocation failure may occur.

6.4 SPI and GC9A01A Round Screen Driver¶

spi:                                            # SPI bus configuration
  id: spi_bus                                   # Unique ID for SPI bus
  mosi_pin: 11                                  # SPI MOSI (data out) pin
  clk_pin: 10                                   # SPI clock pin

display:                                        # Display component configuration
  - platform: ili9xxx                           # Use ILI9XXX display driver
    id: round_display                           # Unique ID for display
    model: GC9A01A                              # Specific display model (1.28" round)
    cs_pin: GPIO9                               # SPI chip select pin
    dc_pin: GPIO3                               # Data/command selection pin
    reset_pin: GPIO14                           # Display reset pin
    invert_colors: true                         # Invert display color polarity
    rotation: 0                                 # Display rotation (0 degrees)

GPIO11 and GPIO10 serve as the SPI data and clock pins, respectively, while GPIO9, GPIO3, and GPIO14 are used for chip select, data/command selection, and reset, respectively. model: GC9A01A lets ESPHome use the driver parameters corresponding to the 1.28-inch 240×240 round screen; invert_colors: true corrects the panel's color polarity, and rotation: 0 keeps the default orientation. When a black screen, inverted colors, or incorrect image orientation occurs, you should first verify these hardware parameters.

6.5 GPIO46 PWM Backlight and Onboard Output¶

output:
  - platform: ledc
    pin: GPIO46
    id: gpio_3_backlight_pwm
  - platform: gpio
    id: power_light
    pin: GPIO40
  - platform: gpio
    id: out1
    pin: GPIO1
  - platform: gpio
    id: out2
    pin: GPIO2

light:
  - platform: monochromatic
    id: back_light
    output: gpio_3_backlight_pwm
    restore_mode: ALWAYS_ON

The LEDC component generates a PWM on GPIO46, the monochromatic light component wraps it as an adjustable backlight, and ALWAYS_ON keeps the backlight on by default after the device restarts. GPIO40, GPIO1, and GPIO2 are the three onboard digital outputs controlled by the startup process. The ID connects the hardware definitions to the on_boot actions, so the ID spelling must be exactly consistent. This lesson turns on the PWM directly; subsequent lessons will adjust the brightness by changing the output level.

6.6 Fonts, LVGL Styles, and Labels¶

font:
  - file: "gfonts://Roboto"
    id: roboto24
    size: 24

lvgl:
  displays:
    - round_display
  default_font: roboto24
  disp_bg_color: white
  style_definitions:
    - id: hello_style
      text_font: roboto24
      text_color: 0x000000
      bg_opa: TRANSP
      align: center
  pages:
    - id: hello_page
      widgets:
        - label:
            id: hello_label
            text: "Hello World!"
            styles: hello_style
            align: CENTER

ESPHome downloads and generates the 24 px Roboto font at compile time; the first compilation requires network access. LVGL uses round_display as the drawing target, sets a white background, and uses hello_style to consecutively define the font, black text, transparent widget background, and centering. The page then creates hello_label and applies this style. The execution chain is "display driver provides the canvas → LVGL builds the white page → style determines appearance → label displays text". If the screen is white but shows no text, you should check the font, style, and label; if there is no white background either, you should check the backlight and SPI.

7. Experimental Observations¶

After display initialization completes, the 240×240 round screen should show a white background with black Hello World! displayed in the center. The text should not be clipped by the round edge, and the screen should not continuously flicker, show corrupted graphics, or restart periodically. If the page remains stable during continuous operation, you can conclude that the power supply, SPI, LCD initialization, font, and LVGL basic chain are working properly.

8. Code Download¶

Official code: Elecrow ESPHome Lesson_Code