ESP-IDF 开发
本节介绍 ESP-IDF 基础示例的编译、烧录、操作方法和运行现象。准备开发板及 USB 数据线,并下载 ESP32-S3-Touch-LCD-1.85B 示例程序。
本章节包含以下部分,请按需阅读:
ESP-IDF 入门教程
初次接触 ESP32 ESP-IDF 开发,想要快速上手?我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 搭建环境
- 第2节 运行实例
- 第3节 创建项目
- 第4节 使用组件
- 第5节 调试程序
- 第6节 FreeRTOS
- 第7节 驱动外设
- 第8节 Wi-Fi 编程
- 第9节 BLE 编程
请注意:该教程使用 ESP32-S3-Zero 作为教学示例,所有硬件代码均基于其引脚布局。在动手实践前,建议您对照手中的开发板引脚图,确认引脚配置无误。
配置 ESP-IDF 开发环境
参考 ESP-IDF 开发环境安装教程 安装环境。
本文使用 ESP-IDF v5.5.4,基础示例共 6 个,位于 examples/esp-idf。图形界面使用 LVGL 9.5.0,请使用随工程提供的组件配置。
以下内容以 Windows 系统为例,使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
此部分图示以安装 ESP-IDF V5.5.2 为例示范,安装时请选用与您开发板示例匹配的 ESP-IDF 版本。
安装 ESP-IDF 开发环境
-
前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具,下文将演示如何使用其离线安装功能。
在页面中点击 Offline Installer 标签,然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本(图示仅为参考,请以实际为准)。

确认选择无误后,点击下载按钮。浏览器将自动同时下载两个文件:一个是 ESP-IDF 离线整合包(.zst),另一个是 ESP-IDF 安装器(.exe)。

请耐心等待两个文件下载完成。
-
下载完成后,双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。
启动后,可在右上角将界面语言切换为中文。

安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

接下来,选择安装路径。建议使用默认路径;若需自定义,请确保路径中不包含中文或空格。确认无误后,点击 开始安装。

-
当看到如下界面时,表示 ESP-IDF 已安装成功。

-
建议同时安装驱动程序。点击 完成安装,然后点击 安装驱动程序。

安装 Visual Studio Code 与 ESP-IDF 扩展
-
下载并安装 Visual Studio Code。
-
安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。
-
在 VS Code 中,点击侧边活动栏中的
扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。
-
在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

-
当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。
| 环境或组件 | 版本或配置 | 说明 |
|---|---|---|
| ESP-IDF | v5.5.4 | 使用与工程一致的 SDK 版本 |
| 目标芯片 | esp32s3 | 工程已设置,无需更换目标 |
| LVGL | 9.5.0 | 由工程依赖配置管理 |
| 板级支持包 | components/esp32_s3_touch_lcd_1_85B | 各示例自带,包含显示、触摸及板载外设适配 |
| 串口波特率 | 115200 | 用于基础示例日志 |
首次构建时会按工程的依赖配置下载所需组件。请保留原有组件配置和依赖锁定文件,不要将 Arduino 的库文件复制到 ESP-IDF 工程中。
编译和烧录
-
在 VS Code 中选择已安装的 ESP-IDF v5.5.4 环境。
-
打开要运行的单个示例目录,例如
examples/esp-idf/01_lvgl_demo。目录中应包含CMakeLists.txt,工程已设置目标芯片为 ESP32-S3。 -
通过 USB 连接开发板,在该示例目录打开 ESP-IDF 终端。
-
执行以下命令编译、烧录并查看串口日志,将
COM5替换为实际串口:idf.py buildidf.py -p COM5 flash monitor -
串口监视器使用 115200 波特率。烧录后按下文检查结果,按
Ctrl+]退出监视器。
每个示例自带板级支持包(BSP,Board Support Package)和本地驱动,可复制完整的单个示例目录使用;保留其 components、配置文件和依赖锁定文件。
烧录基础示例后,开发板会运行该示例。天气、音乐播放器、相册、小智 AI 等完整 APP 位于独立的出厂工程 examples/factory。需要恢复桌面时,重新烧录 ESP32-S3-Touch-LCD-1.85B 出厂固件。
示例程序
示例位于源码包的 examples/esp-idf 目录。以下每个示例均为独立工程,打开对应目录后,按 编译和烧录 中的步骤运行。
| 示例目录 | 功能 | 查看结果 |
|---|---|---|
| 01_lvgl_demo | 按钮触摸计数及背光亮度调节 | LCD |
| 02_sd_card | 写入、读回并校验 SD 卡测试文件 | LCD、串口 |
| 03_qmi8658 | 三轴加速度、角速度及芯片内部温度 | 串口 |
| 04_pcf85063 | RTC 日期和时间读取、设置 | 串口 |
| 05_bq27220 | 电量、电压、电流、容量及电量计状态 | 串口 |
| 06_mic_test | 双麦电平监测、录音及分通道回放 | LCD、喇叭 |
01_lvgl_demo
程序说明
使用板级支持包初始化屏幕和触摸,创建 LVGL 按钮、计数标签和亮度滑块。
硬件连接
使用 USB 数据线连接开发板与电脑,无需 SD 卡或喇叭。
代码分析
bsp_display_start():初始化显示、触摸和 LVGL 运行环境。bsp_display_lock()与bsp_display_unlock():在创建控件时保护 LVGL 操作。clicked():响应按钮点击,更新触摸计数。brightness():读取滑块值,通过bsp_display_brightness_set()调节背光。bsp_display_show():在首帧完成后点亮屏幕。
运行效果
屏幕显示 "LVGL Touch Demo",初始计数为 Touch count: 0。每点击一次 "Touch me",计数加 1。拖动 "Backlight brightness" 滑块,背光在 10%~100% 范围内变化。
按 RESET 可重新启动演示,计数恢复为 0。若屏幕持续不亮,查看串口中显示、触摸及背光初始化是否报错。

02_sd_card
程序说明
向 SD 卡写入测试文件,读回并比较长度和内容,在串口和 LCD 上显示测试结果。
硬件连接
每次运行会覆盖 SD 卡根目录下的 test.txt。请先备份同名文件,使用 FAT32 格式测试卡。本 IDF 示例不会格式化 SD 卡。
上电前插入 SD 卡,再使用 USB 数据线连接开发板与电脑,无需预先创建测试文件。
代码分析
run_sd_test():初始化挂载所需资源,通过bsp_sdcard_acquire()挂载 SD 卡,输出容量、文件系统空间及剩余空间。- 使用
fopen()、fwrite()写入test.txt,再通过fread()读回并校验。 - 测试完成后释放并卸载 SD 卡,保留文件供电脑查看。
show_result():在测试结束后创建 LVGL 结果界面,显示状态、错误码、文件路径及读回内容。
运行效果
程序上电后自动进行一次测试,完成后点亮屏幕显示结果。成功时:
-
串口依次输出
SD card mounted、Write successful、Read successful和Write/read verification: ESP_OK。 -
屏幕显示
Write / read passed、ESP_OK、文件路径/sdcard/test.txt和以下读回内容:ESP32-S3-Touch-LCD-1.85B SD test
成功卸载后,串口显示 SD card unmounted; test.txt remains on the card。可断电取卡,在电脑中查看根目录下的 test.txt。按 RESET 可重新测试,仅插入 SD 卡不会自动重测。
失败时屏幕显示对应阶段:SD card not mounted、File write failed、File read failed 或 Card cleanup failed。其中 Card cleanup failed 表示读写通过,但卸载失败;请结合错误码及串口日志排查。

03_qmi8658
程序说明
读取板载 QMI8658 六轴传感器,通过串口输出三轴加速度、角速度和芯片内部温度。
硬件连接
使用 USB 数据线连接开发板与电脑,无需外接传感器。
代码分析
bsp_imu_init():初始化运动传感器。bsp_imu_get_data():读取加速度、角速度及内部温度,成功时输出数据,失败时打印错误码。- 主循环通过
vTaskDelay()设置约 500 ms 的读取间隔。
运行效果
串口约每 500 ms 输出三轴加速度 Accel [g]、角速度 gyro [deg/s] 和内部温度 die。轻轻倾斜或转动开发板,数据随之变化;静止时仍会测到重力,各轴不一定为零。
die 为 QMI8658 芯片内部温度,不能作为环境温湿度测量结果。本示例不初始化 LCD,屏幕不亮属于正常现象。

04_pcf85063
程序说明
读取板载 PCF85063 实时时钟(RTC,Real-Time Clock)的日期和时间,并提供设置起始时间的代码示例。
硬件连接
先接好配套 3.7 V 锂电池,再使用 USB 数据线连接开发板与电脑,并保持电池连接。 RTC 持续计时需要保持供电。
代码分析
bsp_rtc_init():初始化 RTC;保留有效日期,仅在检测到停振或无效日期时写入默认时间。SET_TIME_ON_BOOT:默认为false,不会在每次启动时覆盖有效时间。改为true后,通过bsp_rtc_set_datetime()写入initial。bsp_rtc_get_datetime():循环读取日期和时间,约每秒输出一次。读取失败时打印错误码,并在后续循环重试初始化。
运行效果
串口每秒输出一次日期和时间,秒数持续递增。本示例不点亮屏幕,不进行联网校时。
RTC 日期有效时,复位后继续读取原有时间;检测到停振或无效日期时,BSP 初始化为 2025 年 1 月 1 日 12:00:00。
如需演示设置时间,将 main/main.cpp 中的 SET_TIME_ON_BOOT 改为 true。代码中的 initial 为 2026 年 1 月 1 日 12:00:00,可按需修改后重新编译烧录;启用后,每次启动都会重新写入该时间。
05_bq27220
程序说明
读取板载 BQ27220 电量计,输出电量、电压、电流、容量、内部温度、循环次数及状态信息。
硬件连接
先接好配套 3.7 V / 500 mAh 锂电池,再连接 USB 数据线,并保持电池连接。 接入前核对正负极;更换电池时,先断开 USB 和电池,再按上述顺序连接。
代码分析
bsp_battery_init():初始化 BQ27220,检查并按需配置配套 500 mAh 电池参数。bsp_battery_get_data():读取状态及电池数据,将电流转换为有符号数,将温度转换为摄氏度。- 主循环每秒读取一次,先打印
Status、operation、present和initialized;仅在后两项均有效时输出电量等数值,读取失败时打印错误码。
运行效果
串口约每秒更新一次数据,本示例不点亮屏幕。各字段含义如下:
| 字段 | 含义 |
|---|---|
%、mV | 芯片估算的剩余电量及电压 |
mA | 实时电流,正值表示充电,负值表示放电 |
RC | 剩余容量,单位 mAh |
FCC | 芯片报告的满充容量,单位 mAh |
design | 设计容量,当前使用 500 mAh 参数 |
avg | 平均电流,单位 mA |
gauge | BQ27220 内部温度,不是环境或电芯温度 |
cycles | 芯片报告的循环次数 |
仅接 USB 时,即使日志出现 present=1、100% 或电压读数,也不能据此确认已插入电池或实际电量。请按上述顺序连接电池,再比较电池供电和接入 Type-C 后的电流变化。
06_mic_test
程序说明
通过触摸界面监测 MIC1、MIC2 两路麦克风电平,同时录音并分别回放,验证麦克风采集和喇叭输出。
硬件连接
上电前接好匹配的喇叭,再使用 USB 数据线连接开发板与电脑。无需 SD 卡或网络。
代码分析
main/main.cpp:初始化显示、音频编解码器,将回放音量设置为 60%,创建 "Mic Test" 界面。MicTest::work():采集两路麦克风数据,计算电平,并将最长 5 秒的录音保存到 PSRAM。MicTest::play():提取选定麦克风的录音,通过喇叭回放。MicTest::refresh():更新两路音量条、dBFS 数值、录音时长和按钮状态。
运行效果
启动后屏幕显示 "Mic Test",按以下步骤体验:
- 对着麦克风说话,观察 MIC1、MIC2 音量条及 dBFS 数值是否随声音变化。
- 点击 "Record",同时录制两路麦克风,最长 5 秒后自动停止;录制期间可点击 "Stop" 提前结束。
- 分别点击 "MIC1"、"MIC2",通过喇叭回放对应通道。播放时可点击 "Stop" 中止,结束后恢复电平监测。
录音参数为 16 kHz、双声道、16 位 PCM,临时保存在 PSRAM 中,新录音覆盖上一段,复位或断电后清除,不写入 SD 卡或 Flash。未录音时,两路回放按钮不可用。
电平监测及录音期间关闭喇叭输出,不会实时外放麦克风声音。CLIPPED 表示曾检测到采样削波,可降低说话音量或增大与麦克风的距离后重新录音。dBFS 为相对数字满量程的电平,不是环境声压级。
出现错误时,界面显示错误信息,点击 "Retry" 可重试。若回放无声,检查喇叭连接、录音时长和屏幕错误提示。本示例不启动语音唤醒或声学回声消除(AEC,Acoustic Echo Cancellation)。

常见问题
- **切换 IDF 后编译报错:**确认当前终端使用 v5.5.4,执行
idf.py fullclean后重新编译,不沿用其他 IDF 版本生成的构建缓存。 - **找不到 BSP 或依赖组件:**打开包含
CMakeLists.txt的单个示例目录,保留完整components目录及依赖配置,检查组件下载是否成功。 - **无串口输出:**检查 USB 数据线、串口选择及 115200 波特率,关闭其他占用串口的软件,再按 RESET。
- **屏幕不亮:**先对照示例列表确认是否有显示界面;
03_qmi8658、04_pcf85063和05_bq27220仅输出串口日志。
SD 卡重测、RTC 设置、电池数据及麦克风操作等问题,参见 ESP32-S3-Touch-LCD-1.85B ESP-IDF 基础示例 FAQ。