跳到主要内容

ESP-IDF 开发

本章节介绍 ESP-IDF 开发环境配置方法和产品示例程序。

ESP-IDF 入门教程​

初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。

请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。

配置 ESP-IDF 开发环境​

备注

以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。

版本选择

此部分图示以安装 ESP-IDF V5.5.2 为例示范，安装时请选用与您开发板示例匹配的 ESP-IDF 版本。

安装 ESP-IDF 开发环境​

  1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

    在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你需要的 ESP-IDF 版本（图示仅为参考，请以实际为准）。

    下载 EIM 和整合包

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

    下载 EIM 和整合包2

    请耐心等待两个文件下载完成。

  2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

    启动后，可在右上角将界面语言切换为中文。

    切换 EIM 语言

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

    自动检测整合包

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

    选择安装路径

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

    安装成功

  4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

    用 ESP-IDF 安装管理器安装驱动

安装 Visual Studio Code 与 ESP-IDF 扩展​

  1. 下载并安装 Visual Studio Code。

  2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

  3. 在 VS Code 中,点击侧边活动栏中的 扩展图标 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

  4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

    在 VS Code 中搜索并安装 ESP-IDF 扩展

  5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

版本要求

本页的 7 个 ESP-IDF 示例已使用 ESP-IDF v5.5.4 编译通过，目标芯片为 esp32c5。使用其他 ESP-IDF 版本时，组件依赖和接口可能不一致。

编译和烧录示例​

新版产品 示例程序仓库 中，ESP-IDF 示例位于 examples/esp-idf 目录。每个子目录都是独立工程，共 7 个示例。

示例目录版本

本页按当前 GitHub 仓库的目录和编号说明。若已有工程仍使用 example/ESP-IDF-V554 目录，且包含 01_factory，则为旧版工程，请从 ESP32-C5-Touch-LCD-3.5 相关资料 重新下载当前仓库，避免示例编号不一致。

在 ESP-IDF v5.5.4 命令行环境中进入需要运行的工程目录，执行：

idf.py set-target esp32c5
idf.py build
idf.py -p PORT flash monitor

将 PORT 替换为开发板对应的串口，例如 Windows 下的 COM8。按 Ctrl+] 退出串口监视器。

已提供工程配置

示例工程已包含 sdkconfig 和 sdkconfig.defaults。如果修改了 ESP-IDF 版本或工程配置，请根据编译输出检查目标芯片、Flash 和 PSRAM 设置。

前 6 个示例随附板级支持包（BSP，Board Support Package）；07_AXP2101 独立配置 I2C。BSP 中 BOOT 对应 GPIO28，低电平有效；PWR 检测对应扩展 IO 的 EXIO6，高电平有效，不能将 EXIO6 当作 ESP32-C5 的 GPIO6。

示例程序​

示例列表​

示例目录功能主要验证内容
01_lvgl_demo运行 LVGL Benchmark，初始化触摸输入ST7796、FT6336、背光、LVGL
02_sd_card读写文件并校验内容Micro SD 卡、SDSPI
03_qmi8658周期读取六轴传感器QMI8658、I2C
04_pcf85063设置并周期读取 RTCPCF85063、I2C
05_shtc3周期读取温湿度SHTC3、I2C
06_exio循环翻转 EXIO8～EXIO15IO 扩展芯片、I2C
07_AXP2101读取电源和充电状态AXP2101、电源管理
出厂工程

出厂应用源码单独保留在 examples/factory，不属于上述 7 个外设示例。运行 01_lvgl_demo 会显示 LVGL 基准测试界面，不会显示出厂 APP 桌面。出厂固件的操作方法参见 ESP32-C5-Touch-LCD-3.5 出厂固件使用说明。

01_lvgl_demo​

程序说明

示例初始化 NVS、IO 扩展芯片、ST7796 LCD 和 FT6336 触摸输入，开启背光后运行 lv_demo_benchmark()。该示例用于验证 320 × 480 LCD 和 LVGL 图形刷新。

LCD 复位、触摸复位和背光 PWM 通过 IO 扩展芯片控制。BSP 的背光接口使用 0%～100% 亮度参数，示例调用 bsp_display_backlight_on() 开启背光。

硬件连接

  • 将开发板通过 USB 连接到电脑。

运行效果

LCD 显示 LVGL Benchmark 测试界面，界面会自动切换不同的绘制场景。

02_sd_card​

程序说明

示例先将 LCD 片选引脚 GPIO8 置为高电平，避免 LCD 干扰共用 SPI 总线的 Micro SD 卡。随后挂载 Micro SD 卡，在挂载点下创建 test.txt，写入测试内容，再读回并逐字节校验。

测试文件覆盖

示例会覆盖 SD 卡根目录下已有的 test.txt，运行前请备份该文件。

写入与读取内容一致时，串口输出：

========== TF CARD TEST PASS ==========

硬件连接

  • 上电前，将 FAT32 格式的 Micro SD 卡插入卡槽。
  • 将开发板通过 USB 连接到电脑。

运行效果

03_qmi8658​

程序说明

示例通过 BSP 初始化 QMI8658，将加速度单位设为 m/s²，将角速度单位设为 dps。当有新数据时，程序输出 X、Y、Z 三轴数据，轮询间隔为 200 ms。

硬件连接

  • 将开发板通过 USB 连接到电脑。

运行效果

转动开发板时，串口中的加速度和角速度值随姿态变化。

04_pcf85063​

程序说明

示例在每次启动时将 PCF85063 RTC 设置为 2026-09-22 15:00:00，然后每隔 1 秒读取并输出日期、时间和星期。

如需验证 RTC 持续走时，请移除或注释 pcf85063a_set_time_date() 调用，否则每次启动都会写入固定时间。

硬件连接

  • 将开发板通过 USB 连接到电脑。

运行效果

串口每隔 1 秒输出一次 RTC 日期、时间和星期。

05_shtc3​

程序说明

示例通过 BSP 初始化 SHTC3，然后每隔 1 秒读取并输出温度和相对湿度。

硬件连接

  • 将开发板通过 USB 连接到电脑。

运行效果

正常输出格式如下，实际数值由当前环境决定：

Temperature: 25.00 C, Humidity: 50.00 %

06_exio​

程序说明

示例初始化 I2C 和 IO 扩展芯片，每隔 1 秒翻转 EXIO8～EXIO15 的输出电平。EXIO0～EXIO7 不参与此测试。

硬件连接

  • 将开发板通过 USB 连接到电脑。

运行效果

启动后，串口输出：

Toggle EXIO8-15 every 1000 ms; EXIO0-7 excluded

07_AXP2101​

程序说明

示例通过 I2C 初始化 AXP2101 电源管理芯片，输出各路 DCDC、ALDO、BLDO、CPUSLDO 和 DLDO 的开关状态与电压。程序还会启用 VBUS、电池、系统电压和芯片温度测量，并每隔 20 秒输出一次充电、放电、VBUS 和电池信息。

充电参数在示例中设置为：

  • 预充电电流：50 mA
  • 恒流充电电流：400 mA
  • 终止电流：25 mA
  • 充电截止电压：4.2 V

硬件连接

  • 将开发板通过 USB 连接到电脑。
  • 如需查看电池电压、电量百分比或充放电状态，将符合产品要求的 3.7 V 锂电池连接到电池接口。
保留充电参数限制

修改 AXP2101 充电电流或截止电压前，必须确认电池规格和硬件充电设计允许该参数。

运行效果

串口输出各路电源轨状态、充放电状态、VBUS 电压、电池电压、系统电压和芯片温度。