Skip to main content

Working with ESP-IDF

This section describes how to build, flash, operate, and observe the behavior of the ESP-IDF basic examples. Prepare the development board and USB data cable, and download the ESP32-S3-Touch-LCD-1.85B Example Programs.

This chapter includes 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.

Set Up the ESP-IDF Development Environment​

Please refer to Install ESP-IDF Development Environment to install the environment.

Development Environment Version

This document uses ESP-IDF v5.5.4. There are 6 basic examples in total, located in examples/esp-idf. The graphical interface uses LVGL 9.5.0; please use the component configuration provided with the project.

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.

Environment or ComponentVersion or ConfigurationDescription
ESP-IDFv5.5.4Use the SDK version consistent with the project
Target Chipesp32s3Already set in the project; no need to change the target
LVGL9.5.0Managed by the project dependency configuration
Board Support Packagecomponents/esp32_s3_touch_lcd_1_85BIncluded with each example, containing display, touch, and onboard peripheral adaptation
Serial Baud Rate115200Used for basic example logs

The required components are downloaded according to the project's dependency configuration on the first build. Please keep the original component configuration and dependency lock files, and do not copy Arduino library files into the ESP-IDF project.

Build and Flash​

  1. In VS Code, select the installed ESP-IDF v5.5.4 environment.

  2. Open the directory of a single example to run, for example examples/esp-idf/01_lvgl_demo. The directory should contain CMakeLists.txt, and the project has already set the target chip to ESP32-S3.

  3. Connect the development board via USB, and open the ESP-IDF terminal in that example directory.

  4. Run the following commands to build, flash, and view the serial logs, replacing COM5 with the actual serial port:

    idf.py build
    idf.py -p COM5 flash monitor
  5. The serial monitor uses a 115200 baud rate. After flashing, check the results as described below, and press Ctrl+] to exit the monitor.

Each example comes with its own Board Support Package (BSP) and local drivers, and can be used by copying the complete single example directory; keep its components, configuration files, and dependency lock files.

Basic Examples and Factory Desktop

After flashing a basic example, the development board runs that example. Complete APPs such as Weather, Music Player, Photo Album, and Xiaozhi AI are located in the independent factory project examples/factory. To restore the desktop, re-flash the ESP32-S3-Touch-LCD-1.85B Factory Firmware.

Example Programs​

The examples are located in the examples/esp-idf directory of the source package. Each of the following examples is an independent project; after opening the corresponding directory, run it according to the steps in Build and Flash.

Example DirectoryFunctionView Result
01_lvgl_demoButton touch counter and backlight brightness adjustmentLCD
02_sd_cardWrite, read back, and verify the TF card test fileLCD, serial port
03_qmi8658Three-axis acceleration, angular velocity, and chip internal temperatureSerial port
04_pcf85063RTC date and time reading and settingSerial port
05_bq27220Battery level, voltage, current, capacity, and fuel gauge statusSerial port
06_mic_testDual-microphone level monitoring, recording, and per-channel playbackLCD, speaker

01_lvgl_demo​

Program Description​

Initializes the screen and touch through the Board Support Package, and creates an LVGL button, count label, and brightness slider.

Hardware Connection​

Connect the development board to the computer using a USB data cable; no TF card or speaker is required.

Code Analysis​

  • bsp_display_start(): Initializes the display, touch, and LVGL runtime environment.
  • bsp_display_lock() and bsp_display_unlock(): Protect LVGL operations when creating widgets.
  • clicked(): Responds to button clicks and updates the touch count.
  • brightness(): Reads the slider value and adjusts the backlight through bsp_display_brightness_set().
  • bsp_display_show(): Turns on the screen after the first frame is complete.

Expected Behavior​

The screen displays "LVGL Touch Demo", with the initial count being Touch count: 0. Each time "Touch me" is tapped, the count increases by 1. Dragging the "Backlight brightness" slider changes the backlight within the range of 10% to 100%.

Press RESET to restart the demonstration, and the count returns to 0. If the screen stays off, check whether the serial port reports errors in display, touch, or backlight initialization.

01_lvgl_demo Touch Counter and Backlight Brightness Adjustment

02_sd_card​

Program Description​

Writes a test file to the TF card, reads it back, compares the length and content, and displays the test result on the serial port and LCD.

Hardware Connection​

Test File Overwrite

Each run overwrites test.txt in the root directory of the TF card. Please back up any file with the same name first, and use a FAT32-format test card. This IDF example does not format the TF card.

Insert the TF card before powering on, then connect the development board to the computer with a USB data cable; there is no need to create a test file in advance.

Code Analysis​

  • run_sd_test(): Initializes the resources required for mounting, mounts the TF card through bsp_sdcard_acquire(), and outputs the capacity, file system space, and free space.
  • Uses fopen() and fwrite() to write test.txt, then reads it back and verifies it through fread().
  • After the test is complete, releases and unmounts the TF card, retaining the file for viewing on a computer.
  • show_result(): Creates the LVGL result interface after the test ends, displaying the status, error code, file path, and read-back content.

Expected Behavior​

The program automatically runs one test after power-on, then turns on the screen to display the result. On success:

  • The serial port outputs SD card mounted, Write successful, Read successful and Write/read verification: ESP_OK in sequence.

  • The screen displays Write / read passed, ESP_OK, the file path /sdcard/test.txt, and the following read-back content:

    ESP32-S3-Touch-LCD-1.85B SD test

After successful unmounting, the serial port displays SD card unmounted; test.txt remains on the card. You can power off and remove the card to view test.txt in the root directory on a computer. Press RESET to test again; simply inserting a TF card will not trigger an automatic retest.

On failure, the screen displays the corresponding stage: SD card not mounted, File write failed, File read failed and Card cleanup failed. Here, Card cleanup failed indicates that read/write passed but unmounting failed; troubleshoot based on the error code and serial logs.

02_sd_card Read/Write Verification Successful and File Content Display

03_qmi8658​

Program Description​

Reads the onboard QMI8658 six-axis sensor and outputs three-axis acceleration, angular velocity, and chip internal temperature through the serial port.

Hardware Connection​

Connect the development board to the computer with a USB data cable; no external sensor is required.

Code Analysis​

  • bsp_imu_init(): Initializes the motion sensor.
  • bsp_imu_get_data(): Reads acceleration, angular velocity, and internal temperature, outputs the data on success, and prints the error code on failure.
  • The main loop sets a read interval of about 500 ms through vTaskDelay().

Expected Behavior​

The serial port outputs the three-axis acceleration Accel [g], angular velocity gyro [deg/s], and internal temperature die about every 500 ms. Gently tilt or rotate the development board, and the data changes accordingly; gravity is still measured when stationary, so each axis is not necessarily zero.

die is the internal temperature of the QMI8658 chip and cannot be used as an ambient temperature and humidity measurement. This example does not initialize the LCD, so the screen staying off is normal.

03_qmi8658 Serial Log of Acceleration, Angular Velocity, and On-chip Temperature

04_pcf85063​

Program Description​

Reads the date and time of the onboard PCF85063 real-time clock (RTC) and provides a code example for setting the initial time.

Hardware Connection​

First connect the included 3.7 V lithium battery, then connect the development board to the computer with a USB data cable, and keep the battery connected. Continuous RTC timekeeping requires power to be maintained.

Code Analysis​

  • bsp_rtc_init(): Initializes the RTC; retains a valid date and writes the default time only when an oscillator stop or invalid date is detected.
  • SET_TIME_ON_BOOT: Defaults to false, so a valid time is not overwritten on every startup. When changed to true, initial is written through bsp_rtc_set_datetime().
  • bsp_rtc_get_datetime(): Reads the date and time in a loop, outputting about once per second. On read failure, prints the error code and retries initialization in subsequent loops.

Expected Behavior​

The serial port outputs the date and time once per second, and the seconds continue to increase. This example does not turn on the screen and does not perform network time synchronization.

When the RTC date is valid, the original time continues to be read after a reset; when an oscillator stop or invalid date is detected, the BSP initializes it to January 1, 2025, 12:00:00.

To demonstrate setting the time, change SET_TIME_ON_BOOT in main/main.cpp to true. The initial in the code is January 1, 2026, 12:00:00 and can be modified as needed and recompiled and flashed; once enabled, this time is written again on every startup.

04_pcf85063 RTC Initialization and Continuous Timekeeping Serial Log

05_bq27220​

Program Description​

Reads the onboard BQ27220 fuel gauge and outputs battery level, voltage, current, capacity, internal temperature, cycle count, and status information.

Hardware Connection​

First connect the included 3.7 V / 500 mAh lithium battery, then connect the USB data cable, and keep the battery connected. Verify the polarity before connecting; when replacing the battery, first disconnect the USB and battery, then connect them in the above order.

Code Analysis​

  • bsp_battery_init(): Initializes the BQ27220, checks and configures the parameters of the included 500 mAh battery as needed.
  • bsp_battery_get_data(): Reads the status and battery data, converts the current to a signed value, and converts the temperature to degrees Celsius.
  • The main loop reads once per second, first printing Status, operation, present, and initialized; it outputs values such as battery level only when the latter two are both valid, and prints the error code on read failure.

Expected Behavior​

The serial port updates the data about once per second; this example does not turn on the screen. The meaning of each field is as follows:

FieldDescription
%, mVRemaining battery level and voltage estimated by the chip
mAReal-time current; a positive value indicates charging, and a negative value indicates discharging
RCRemaining capacity, in mAh
FCCFull charge capacity reported by the chip, in mAh
designDesign capacity; the 500 mAh parameter is currently used
avgAverage current, in mA
gaugeInternal temperature of the BQ27220, not the ambient or cell temperature
cyclesCycle count reported by the chip

When only USB is connected, even if the log shows present=1, 100%, or voltage readings, this cannot be used to confirm that a battery is inserted or to determine the actual battery level. Please connect the battery in the above order, then compare the current changes between battery power and Type-C connection.

05_bq27220 Serial Log of Battery Level, Voltage, Current, and Status

06_mic_test​

Program Description​

Monitors the levels of the MIC1 and MIC2 microphones through the touch interface, records audio, and plays it back separately to verify microphone capture and speaker output.

Hardware Connection​

Connect a matching speaker before powering on, then connect the development board to the computer with a USB data cable. No TF card or network is required.

Code Analysis​

  • main/main.cpp: Initializes the display and audio codec, sets the playback volume to 60%, and creates the "Mic Test" interface.
  • MicTest::work(): Captures data from both microphones, calculates the level, and saves up to 5 seconds of recording to PSRAM.
  • MicTest::play(): Extracts the recording of the selected microphone and plays it back through the speaker.
  • MicTest::refresh(): Updates the two volume bars, dBFS values, recording duration, and button states.

Expected Behavior​

After startup, the screen displays "Mic Test". Experience it with the following steps:

  1. Speak into the microphone and observe whether the MIC1 and MIC2 volume bars and dBFS values change with the sound.
  2. Tap "Record" to record both microphones simultaneously; recording stops automatically after a maximum of 5 seconds, and you can tap "Stop" to end it early during recording.
  3. Tap "MIC1" and "MIC2" respectively to play back the corresponding channel through the speaker. During playback, you can tap "Stop" to abort; after it ends, level monitoring resumes.

The recording parameters are 16 kHz, stereo, 16-bit PCM, temporarily saved in PSRAM; new recordings overwrite the previous one and are cleared after a reset or power loss, and are not written to the TF card or Flash. When no recording has been made, the two playback buttons are unavailable.

Speaker output is turned off during level monitoring and recording, so the microphone sound is not played externally in real time. CLIPPED indicates that sample clipping has been detected; you can lower your speaking volume or increase the distance from the microphone and record again. dBFS is the level relative to digital full scale, not the ambient sound pressure level.

If an error occurs, the interface displays an error message, and you can tap "Retry" to try again. If there is no sound during playback, check the speaker connection, recording duration, and on-screen error prompts. This example does not enable voice wake-up or Acoustic Echo Cancellation (AEC).

06_mic_test Dual-Microphone Level, Recording, and Per-Channel Playback

Troubleshooting​

  • Compilation errors after switching IDF: Confirm that the current terminal uses v5.5.4, run idf.py fullclean, and then build again; do not reuse build caches generated by other IDF versions.
  • BSP or dependency components not found: Open the single example directory containing CMakeLists.txt, keep the complete components directory and dependency configuration, and check whether the component download succeeded.
  • No serial output: Check the USB data cable, serial port selection, and 115200 baud rate, close other software that is occupying the serial port, and then press RESET.
  • Screen stays off: First refer to the example list to confirm whether the example has a display interface; 03_qmi8658, 04_pcf85063, and 05_bq27220 output serial logs only.

For issues such as TF card retesting, RTC setting, battery data, and microphone operation, see ESP32-S3-Touch-LCD-1.85B ESP-IDF Basic Examples FAQ.