Skip to main content

Working with ESP-IDF

Note

When using the device, keep the screen brightness below 50% and avoid running it at full brightness for extended periods. Excessive brightness will raise the screen temperature and may cause dark shadows to appear on the display.

If display issues occur, power off the board and let it rest for a while before flashing a program with lower brightness settings.

This chapter contains the following sections. Please read as needed:

ESP-IDF Getting Started​

New to ESP32 ESP-IDF development and looking to get started quickly? We have prepared a general Getting Started Tutorial for you.

Please Note: This tutorial uses the ESP32-S3-Zero as a teaching example, and all hardware code is based on its pinout. Before you start, it is recommended that you check the pinout of your development board to ensure the pin configuration is correct.

Setting Up the Development Environment​

Please refer to Install ESP-IDF Development Environment.

Version Note

The ESP32-C5-LCD-1.47 examples require ESP-IDF v5.3.0 or newer.

note

The following guide uses Windows as an example, demonstrating development using VS Code + the ESP-IDF extension. macOS and Linux users should refer to the official documentation.

Version Selection

The screenshots in this section use ESP-IDF V5.5.2 as an example. When installing, please select the ESP-IDF version that matches your board's example.

Install the ESP-IDF Development Environment​

  1. Download the installation manager from the ESP-IDF Installation Manager page. This is Espressif's latest cross-platform installer. The following steps demonstrate how to use its offline installation feature.

    Click the Offline Installer tab on the page, then select Windows as the operating system and the ESP-IDF version you need (the version shown in the screenshot is for reference only — choose the version that fits your actual needs).

    Download EIM and offline package

    After confirming your selection, click the download button. The browser will automatically download two files: the ESP-IDF Offline Package (.zst) and the ESP-IDF Installer (.exe).

    Download EIM and offline package 2

    Please wait for both files to finish downloading.

  2. Once the download is complete, double-click to run the ESP-IDF Installer (eim-gui-windows-x64.exe).

    The installer will automatically detect if the offline package exists in the same directory. Click Install from archive.

    Auto-detect offline package

    Next, select the installation path. We recommend using the default path. If you need to customize it, ensure the path does not contain Chinese characters or spaces. Click Start installation to proceed.

    Select installation path

  3. When you see the following screen, the ESP-IDF installation is successful.

    Installation successful

  4. We recommend installing the drivers as well. Click Finish installation, then select Install driver.

    Install drivers via ESP-IDF Installation Manager

Install Visual Studio Code and the ESP-IDF Extension​

  1. Download and install Visual Studio Code.

  2. During installation, it is recommended to check Add "Open with Code" action to Windows Explorer file context menu to facilitate opening project folders quickly.

  3. In VS Code, click the Extensions icon Extensions Icon in the Activity Bar on the side (or use the shortcut Ctrl + Shift + X) to open the Extensions view.

  4. Enter ESP-IDF in the search box, locate the ESP-IDF extension, and click Install.

    Search and install ESP-IDF extension in VS Code

  5. For ESP-IDF extension versions ≥ 2.0, the extension will automatically detect and recognize the ESP-IDF environment installed in the previous steps, requiring no manual configuration.

Example​

The example programs are located in the examples/esp-idf directory of the resource package. Each example's sdkconfig.defaults already specifies the target chip as esp32c5, so you generally do not need to run idf.py set-target esp32c5 again.

Building and Flashing​

Navigate to any ESP-IDF example directory and run:

cd esp-idf/02_lvgl_hello
idf.py build flash monitor

If you need to specify a serial port, replace COMx with the actual port, for example COM5:

idf.py -p COMx build flash monitor

Example List​

Example DirectoryDescription
01_lcd_panel_basicInitialize the LCD without LVGL, draw color bars and a moving color block
02_lvgl_helloStart the BSP LVGL display interface and show a basic UI
03_backlight_fadeAdjust the LCD backlight brightness and display the brightness changes on screen
04_ws2812_rgbControl the onboard WS2812B RGB LED to cycle through different colors
05_sdcard_rwMount a TF card and perform file write and read-back verification
06_spiffs_rwMount the SPIFFS partition in internal Flash and perform file write and read-back verification
07_wifi_scanScan nearby Wi-Fi networks and output the scan results via serial
08_board_showcaseComprehensive demonstration of LCD, backlight, RGB LED, SPIFFS, TF card, and Wi-Fi status

01_lcd_panel_basic​

Example Description​

  • This example initializes the ST7789 LCD via the BSP without starting LVGL.
  • The LCD first displays a multi-color stripe background, then shows a moving color block to check display and partial refresh functionality.

Hardware Connection​

  • Connect the development board to the computer.
  • This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis​

  • app_main(): Creates the LCD panel, initializes backlight, registers the transfer-complete callback, and starts the display flow.
  • bsp_display_new(): Creates the LCD panel and panel IO objects.
  • bsp_display_brightness_init() and bsp_display_brightness_set(): Initialize and set the LCD backlight.
  • draw_color_bars(): Draws a multi-color stripe background in blocks.
  • esp_lcd_panel_draw_bitmap(): Writes image data to the specified LCD region.
  • draw_moving_bar_region(): Refreshes the moving color block and the background area it covers.

Running Effect​

  • The LCD displays a multi-color stripe background with a color block moving up and down continuously.

ESP32-C5-LCD-1.47 Example 01

02_lvgl_hello​

Example Description​

  • This example starts the BSP LVGL display interface and draws a basic UI on the LCD.
  • The screen shows the board name, LCD resolution, SPI pin information, and a status bar.

Hardware Connection​

  • Connect the development board to the computer.
  • This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis​

  • app_main(): Starts the BSP display service, sets screen orientation and backlight, and creates the LVGL UI.
  • bsp_display_start(): Starts the LCD panel and LVGL port.
  • bsp_display_rotate(): Sets the screen rotation.
  • bsp_display_backlight_on(): Turns on the LCD backlight.
  • bsp_display_lock() and bsp_display_unlock(): Protect the LVGL UI creation process.
  • create_ui(): Creates the title, description text, device info, and status bar.

Running Effect​

  • The LCD shows the LVGL example interface, including the board name, LCD parameters, and SPI pin information.

ESP32-C5-LCD-1.47 Example 02

03_backlight_fade​

Example Description​

  • This example uses bsp_display_brightness_set() to adjust the LCD backlight brightness.
  • The LVGL page simultaneously displays the current brightness percentage and a progress bar.

Hardware Connection​

  • Connect the development board to the computer.
  • This example uses only the onboard LCD and backlight; no external modules are required.

Code Analysis​

  • app_main(): Starts the BSP display service, creates the brightness UI, and enters the brightness loop.
  • create_ui(): Creates the brightness title, percentage label, and progress bar.
  • bsp_display_brightness_set(): Sets the LCD backlight according to the current percentage.
  • update_ui(): Updates the LVGL label and progress bar values.
  • bsp_display_lock() and bsp_display_unlock(): Protect the LVGL widget update process.

Running Effect​

  • The LCD backlight brightness cycles, and the percentage and progress bar on the screen update synchronously.

ESP32-C5-LCD-1.47 Example 03

04_ws2812_rgb​

Example Description​

  • This example initializes the onboard WS2812B RGB LED and cycles through different colors.
  • This example is mainly used to verify the onboard RGB LED control functionality.

Hardware Connection​

  • Connect the development board to the computer.
  • This example uses only the onboard RGB LED; no external modules are required.

Code Analysis​

  • app_main(): Initializes the RGB LED and enters the color loop.
  • bsp_ws2812b_init(): Initializes the onboard WS2812B LED.
  • bsp_setledcolor(): Sets the red, green, and blue brightness for the specified LED.
  • vTaskDelay(): Controls the color switching interval.

Running Effect​

  • The onboard WS2812B RGB LED switches colors in sequence.

05_sdcard_rw​

Example Description​

  • This example mounts a TF card via SDSPI and performs file write and read-back verification.
  • The LCD page shows the TF card mount, write, read, and result statuses.

Hardware Connection​

  • Connect the development board to the computer.
  • Insert a FAT or FAT32-formatted TF card into the board.

Code Analysis​

  • app_main(): Starts the LCD and LVGL UI, mounts the TF card, and performs the read/write test.
  • bsp_sdcard_mount(): Mounts the TF card.
  • sd_write_file(): Writes a test file to the TF card.
  • sd_read_file(): Reads back the test file content and verifies data consistency.
  • set_item() and set_summary(): Update the step status and final result on the LCD.
  • bsp_sdcard_unmount(): Unmounts the TF card after the test completes.

Running Effect​

  • The LCD displays the TF card capacity, file write/read results, and the serial outputs detection information simultaneously.

ESP32-C5-LCD-1.47 Example 05

06_spiffs_rw​

Example Description​

  • This example mounts the SPIFFS partition named storage.
  • The program writes a test file, reads it back, and outputs the content via serial.

Hardware Connection​

  • Connect the development board to the computer.
  • This example uses a custom partition table in the project and does not require external modules.

Code Analysis​

  • app_main(): Mounts SPIFFS, writes a test file, reads it back, and outputs the verification result.
  • bsp_spiffs_mount(): Mounts the storage SPIFFS partition.
  • fopen(), fwrite() and fread(): Perform file write and read-back operations.
  • bsp_spiffs_unmount(): Unmounts SPIFFS after the test completes.

Running Effect​

  • The serial outputs SPIFFS mount status, file read/write results, and the test completion status.

ESP32-C5-LCD-1.47 Example 06

07_wifi_scan​

Example Description​

  • This example uses the ESP32-C5 built-in Wi-Fi to scan for nearby networks.
  • The serial outputs information such as SSID, RSSI, channel, and authentication mode.

Hardware Connection​

  • Connect the development board to the computer.
  • Ensure there are 2.4 GHz or 5 GHz Wi-Fi networks within range.

Code Analysis​

  • app_main(): Initializes NVS and Wi-Fi STA mode, and creates a scan task.
  • init_nvs(): Initializes NVS for use by the Wi-Fi component.
  • init_wifi_sta(): Initializes Wi-Fi and sets it to STA mode.
  • wifi_scan_task(): Periodically performs Wi-Fi scans and outputs the results.
  • ssid_to_printable_ascii(): Filters non-printable characters for proper SSID display over serial.

Running Effect​

  • The serial periodically outputs Wi-Fi scan results, including the number of networks, SSID, RSSI, and channel information.

ESP32-C5-LCD-1.47 Example 07

08_board_showcase​

Example Description​

  • This example comprehensively tests the LCD, backlight, WS2812B RGB LED, SPIFFS, TF card, and Wi-Fi scanning.
  • The LCD page shows the status of each feature as RUN, PASS, WARN or FAIL.
  • The RGB LED changes color according to the final test result.

Hardware Connection​

  • Connect the development board to the computer.
  • If you want to test the TF card, insert a FAT or FAT32-formatted TF card into the board.

Code Analysis​

  • app_main(): Starts the BSP display service, sets screen orientation and backlight, and creates the comprehensive test task.
  • create_ui(): Creates the board resource status panel.
  • showcase_task(): Sequentially checks the LCD, RGB LED, SPIFFS, TF card, and Wi-Fi.
  • write_read_file(): Performs file write and read-back verification on SPIFFS or the TF card.
  • wifi_scan_once(): Performs a single Wi-Fi scan and generates a status text.
  • set_item(): Updates the status and description text for each feature.
  • bsp_setledcolor(): Sets the RGB LED color according to the final status.

Running Effect​

  • The LCD shows the test result for each feature; after completion, the final status is displayed at the bottom, and the RGB LED simultaneously shows the final status color.

ESP32-C5-LCD-1.47 Example 08

Board Showcase Status Description​

08_board_showcase displays the test result for each feature on the LCD, and uses the RGB LED to indicate the overall status.

LED StateMeaning
GreenAll items are PASS.
YellowThere is a WARN, such as no TF card inserted or no Wi-Fi networks found.
RedThere is a FAIL, indicating a feature test has failed.

Instructions:

  • If no TF card is inserted, the TF item shows CHECK or No card, and the final LED state is yellow.
  • If no Wi-Fi networks are found, the Wi-Fi item shows a warning, and the final LED state is yellow.
  • SPIFFS may prompt for formatting on first run; this is normal.

Usage Notes​

  • Before running 05_sdcard_rw, insert a FAT or FAT32-formatted TF card.
  • 06_spiffs_rw and 08_board_showcase use a custom partition table that includes the storage SPIFFS partition.
  • The LCD and TF share SPI clock and MOSI pins, with the SPI bus initialized by the BSP.
  • The onboard RGB LED examples pass color parameters in the order red, green, blue.
  • The current BSP does not support touch, buttons, audio, or IMU functions.