Skip to main content

Working with ESP-IDF

Overview​

The ESP32-S3-Touch-LCD-7C board features a 7inch capacitive touchscreen, audio module, and commonly used peripherals, making it suitable for applications such as graphical user interface display, voice interaction, and human‑machine interface development.

info

For the ESP32-S3-Touch-LCD-7C development board, the examples default to ESP-IDF V5.5.3. If compilation fails with other versions, you can fall back to this version for testing.

Getting Started​

This chapter includes the following sections:

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​

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.

warning

If installation fails or a reinstall is needed, you can try deleting the C:\Users\%Username%\esp and C:\Users\%Username%\.espressif folders and then retry.

Flashing Example​

  1. After installing the ESP-IDF development environment, select the folder to open the example.

    Open folder in VS Code

  2. In the pop-up window, select the example under the ESP-IDF directory within the extracted example package, and click to select a file.

    Open file in VS Code

  3. To upload the corresponding code to the ESP32-S3, use a Type-C to Type-A cable to connect the USB TO UART Type-C interface of the ESP32-S3-Touch-LCD-7C to a USB port on your computer.

  4. If this is the first time flashing a new project, you need to select the detected COM port. For example, here it is detected as COM36.

    Select COM port

  5. Select the download method: UART.

    Select download method

  6. Next, select the main chip as ESP32S3.

    Select main chip

    • Select the openocd path. This does not affect the process, so choose the first one.

    Select openocd path

  7. Click the one‑click Build Flash Monitor button below to sequentially execute Build --> Flash --> Monitor.

    Select Build Flash Monitor button

  8. The development board has an onboard automatic download circuit, so no manual operation is required for automatic download. Wait for compilation and flashing to complete. The first compilation may take a while.

    Compilation and download complete

Example​

Below are the purpose, key points, and operational effects for each example (for quick start).

ExampleBasic Description
01_I2CTest I2C interface communication
02_RTCTest RTC real-time clock functionality
03_LCDTest LCD display functionality
04_ISOLATION_IOTest isolated I/O functionality
05_BAT_INFOTest battery information reading
06_SDTest TF card read/write functionality
07_TOUCHTest touchscreen functionality
08_DISPLAY_BMPDisplay BMP images
09_SPEAKER_MICROPHONETest speaker and microphone
10_LVGL_CODECLVGL codec example

01_I2C​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.

Code​

Backlight Control Code
    while (1)
    {
        // Set the IO_EXTENSION_IO_2 pin to high (turn on the backlight)
        IO_EXTENSION_Output(IO_EXTENSION_IO_2, 1);  // Turn on backlight
        vTaskDelay(500 / portTICK_PERIOD_MS);  // Wait for 500 milliseconds

        // Set the IO_EXTENSION_IO_2 pin to low (turn off the backlight)
        IO_EXTENSION_Output(IO_EXTENSION_IO_2, 0);  // Turn off backlight
        vTaskDelay(500 / portTICK_PERIOD_MS);  // Wait for 500 milliseconds
    }

Code Analysis​

  • while (1): Continuously loops the backlight on/off test logic.
  • IO_EXTENSION_Output(IO_EXTENSION_IO_2, 1): Sets IO_2 of the I/O expansion chip to high level to turn on the LCD backlight.
  • IO_EXTENSION_Output(IO_EXTENSION_IO_2, 0): Sets IO_2 to low level to turn off the LCD backlight.
  • vTaskDelay(500 / portTICK_PERIOD_MS): Delays for approximately 500 ms to control the blinking rhythm of the backlight.

Operation Result​

  • You will see the LCD backlight blinking.

02_RTC​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.

Code​

RTC Initialization Code
    // Initialize the I2C interface
    DEV_I2C_Init();

    // Initialize external IO extension chip
    IO_EXTENSION_Init();

    // Initialize PCF85063A RTC
    PCF85063A_Init();

    // Set current time
    PCF85063A_Set_All(Set_Time);

    // Set alarm time
    PCF85063A_Set_Alarm(Set_Alarm_Time);

    // Enable alarm interrupt
    PCF85063A_Enable_Alarm();

Code Analysis​

  • DEV_I2C_Init(): Initializes the I2C bus in preparation for communication with the RTC and I/O expansion chip.
  • IO_EXTENSION_Init(): Initializes the external I/O expansion chip (used for reading/writing peripheral signals such as RTC interrupts).
  • PCF85063A_Init(): Initializes the PCF85063A RTC chip.
  • PCF85063A_Set_All(Set_Time): Sets the current time on the RTC.
  • PCF85063A_Set_Alarm(Set_Alarm_Time): Sets the RTC alarm time.
  • PCF85063A_Enable_Alarm(): Enables the alarm interrupt to trigger alarm notifications.

Operation Result​

  • The RTC time is printed over the serial port.

    ESP32-S3-Touch-LCD-7C-Arduino-example-1

03_LCD​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.

Code Analysis​

  • app_main():
    • Initializes the LCD display.
    • Tests LCD display functionality.
    • Displays text, graphics, and images.

Operation Result​

  • After successful flashing, the screen displays test content.

  • You will see text, graphics, and image display effects.

    ESP32-S3-Touch-LCD-7C-IDF-example-3

04_ISOLATION_IO​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.

Code Analysis​

  • app_main():
    • Initializes the isolated I/O.
    • Tests isolated I/O input and output functionality.

Operation Result​

  • After successful flashing, if all I/O connections are successful, the screen turns green; otherwise, it turns red.

05_BAT_INFO​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.
  • Connect a Lithium battery to the development board.

Code​

Battery Information Display Code
    if (bat_info.ma > 0) {
      sprintf(bat,
              "%d%% | %dmV | %dmA | %dC | TTF=%d min | Rem=%dmAh | FCC=%dmAh | "
              "Cyc=%d | SOH=%d%%",
              bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc, bat_info.ttf,
              bat_info.mah_rem, bat_info.mah_fcc, bat_info.cycles,
              bat_info.soh);

      Paint_DrawString_EN(50, 130, bat, &Font48, GREEN, WHITE);

      waveshare_rgb_lcd_display(BlackImage);
      // Charging: display TTF (time to full)
      ESP_LOGI("BQ27220",
               "%d%% | %dmV | %dmA | %dC | TTF=%d min | Rem=%dmAh | FCC=%dmAh "
               "| Cyc=%d | SOH=%d%%",
               bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc,
               bat_info.ttf, bat_info.mah_rem, bat_info.mah_fcc,
               bat_info.cycles, bat_info.soh);
    } else {
      sprintf(bat,
              "%d%% | %dmV | %dmA | %dC | TTE=%d min | Rem=%dmAh | FCC=%dmAh | "
              "Cyc=%d | SOH=%d%%",
              bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc, bat_info.tte,
              bat_info.mah_rem, bat_info.mah_fcc, bat_info.cycles,
              bat_info.soh);

      Paint_DrawString_EN(50, 130, bat, &Font48, RED, WHITE);

      waveshare_rgb_lcd_display(BlackImage);

      // Discharging: display TTE (time to empty)
      ESP_LOGI("BQ27220",
               "%d%% | %dmV | %dmA | %dC | TTE=%d min | Rem=%dmAh | FCC=%dmAh "
               "| Cyc=%d | SOH=%d%%",
               bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc,
               bat_info.tte, bat_info.mah_rem, bat_info.mah_fcc,
               bat_info.cycles, bat_info.soh);
    }

Code Analysis​

  • bat_info.ma > 0: In the current logic, positive current is treated as charging state; otherwise, it is treated as discharging.
  • sprintf(bat, "...", ...): Formats the battery percentage, voltage, current, temperature, remaining time, and other fields into a string for screen display.
  • Paint_DrawString_EN(...): Draws the battery information on the LCD; uses GREEN for charging and RED for discharging to indicate status.
  • waveshare_rgb_lcd_display(BlackImage): Refreshes the screen to display the drawn content.
  • ESP_LOGI("BQ27220", "...", ...): Outputs the same battery information to the serial log for debugging and cross‑checking.

Operation Result​

  • After successful flashing, the screen displays battery information.

    ESP32-S3-Touch-LCD-7C-IDF-example-05

06_SD​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.
  • Insert a TF card into the development board.

Code Analysis​

  • app_main():
    • Initializes the TF card.
    • Tests TF card read/write functionality.

Operation Result​

  • After successful flashing, the screen displays TF card information and test results.

    ESP32-S3-Touch-LCD-7C-IDF-example-6

07_TOUCH​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.
  • app_main():
    • Initializes the display and touchscreen drivers.
    • Reads touchscreen data and displays it.

Operation Result​

  • After successful flashing, the touchscreen works normally, and the corresponding touch UI elements are displayed on the screen.

08_DISPLAY_BMP​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.
  • Insert a TF card containing BMP images.

Code Analysis​

  • app_main():
    • Initializes the TF card and LCD.
    • Reads and displays BMP images.

Operation Result​

  • After successful flashing, BMP images are displayed on the screen.

    ESP32-S3-Touch-LCD-7C-IDF-example-8

09_SPEAKER_MICROPHONE​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.
  • Connect the speaker and microphone.

Code​

Audio Touch Control Code
        point_data = touch_gt911_read_point(1);
        if (point_data.cnt == 1)
        {
            if (!(prev_x == point_data.x[0] && prev_y == point_data.y[0]))
            {
                if (point_data.x[0] > 390 && point_data.x[0] < 420 &&
                    point_data.y[0] > 420 && point_data.y[0] < 480)
                {
                    Paint_Clear(WHITE);
                    is_playing = true;
                    play_or_pause(is_playing);
                    is_playing = false;
                    play_or_pause(is_playing);

                    Paint_Clear(WHITE);
                    Paint_DrawCircle(405, 450, 15, RED, DOT_PIXEL_2X2, DRAW_FILL_FULL);
                    Paint_DrawString_EN(100, 150, "Click to record/play", &Font48, BLACK, WHITE);
                    waveshare_rgb_lcd_display(BlackImage);

                    prev_x = point_data.x[0];
                    prev_y = point_data.y[0];
                }
            }
        }

Code Analysis​

  • touch_gt911_read_point(1): Reads touch point data from the GT911 touch controller (here, one set of data is taken).
  • point_data.cnt == 1: Only enters the processing logic for a single‑touch event to avoid multi‑touch interference.
  • prev_x / prev_y: Stores the previous touch coordinates to filter out repeated triggers.
  • Coordinate range check: When the touch point falls within (x: 390~420, y: 420~480), it is considered a tap on the control area on the interface.
  • play_or_pause(...): Executes play/pause control according to the current state (in the example, it is called twice in succession to demonstrate the control flow).
  • Paint_DrawCircle(...) / Paint_DrawString_EN(...): Draws the button and prompt text, and refreshes the display via waveshare_rgb_lcd_display(...).

Operation Result​

  • After successful flashing, you can record audio via the microphone and play it back through the speaker.

    ESP32-S3-Touch-LCD-7C-IDF-example-9

10_LVGL_CODEC​

Hardware Connection​

  • Connect the development board to a computer using a USB cable.

Code​

LVGL Codec Initialization Code
    speaker_codec_init();
    speaker_codec_volume_set(50, NULL);
    speaker_player_register_callback(speaker_callback, NULL);
    speaker_player_init();

    // Lock the mutex due to the LVGL APIs are not thread-safe
    if (lvgl_port_lock(-1)) {
        user_lv_demo_music();
        // Release the mutex
        lvgl_port_unlock();
    }
    IO_EXTENSION_Pwm_Output(100); // Set backlight brightness to maximum
    waveshare_rgb_lcd_bl_on(); // Turn on the LCD backlight

Code Analysis​

  • speaker_codec_init(): Initializes the audio codec hardware.
  • speaker_codec_volume_set(50, NULL): Sets the volume to 50 (the exact range depends on the implementation).
  • speaker_player_register_callback(...): Registers a playback callback function to receive playback status events.
  • speaker_player_init(): Initializes the player module.
  • lvgl_port_lock(-1) / lvgl_port_unlock(): LVGL APIs are not thread‑safe, so lock before calling UI functions and unlock afterward.
  • user_lv_demo_music(): Launches the example LVGL music interface.
  • IO_EXTENSION_Pwm_Output(100): Outputs PWM via the I/O expander to set the backlight brightness to maximum.
  • waveshare_rgb_lcd_bl_on(): Turns on the LCD backlight output.

Operation Result​

  • After successful flashing, the LVGL interface is displayed on the screen, and music can be played normally (a TF card must be inserted in advance).

    ESP32-S3-Touch-LCD-7C-IDF-example-10