ESP-IDF

本章节包含以下部分，请按需阅读：

ESP-IDF 入门教程
配置 ESP-IDF 开发环境
示例程序

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-C6-Touch-AMOLED-2.16 开发板，基于 ESP-IDF V5.5.2 开发，建议使用相同版本测试开发，其他版本可能存在兼容性问题

备注

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

安装 ESP-IDF 开发环境

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

在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你要安装的版本。

确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 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 示例程序位于示例程序包的 ESP-IDF 目录中。

示例程序	基础例程说明	依赖库
01_AXP2101_Test	驱动 AXP2101 电源管理芯片，获取相关电源信息	-
02_I2C_QMI8658	打印 QMI 芯片的原始姿态数据	-
03_I2C_PCF85063	打印 RTC 芯片的实时时间	-
04_SD_Card	加载显示 SD 卡的信息	-
05_WIFI_STA	设置为 STA 模式，可接入 AP 获取 IP 地址	-
06_WIFI_AP	设置为 AP 模式，可获取接入设备的 IP 地址	-
07_Audio_Test	扬声器播放麦克风录到的声音	-
08_LVGL_V8_Test	LVGLV8 例程	LVGL V8.*
09_LVGL_V9_Test	LVGLV9 例程	LVGL V9.*
10_FactoryProgram	综合示例	LVGL V9.*

01_AXP2101_Test

【程序说明】

通过驱动 AXP2101 获取电源信息，并打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

axp2101.setDC1Voltage(3300);    //设置DCDC1电压值3.3V
axp2101.setALDO1Voltage(3300);  //设置ALDO1电压值3.3V
axp2101.setALDO2Voltage(3300);  //设置ALDO2电压值3.3V
axp2101.setALDO3Voltage(3300);  //设置ALDO3电压值3.3V
axp2101.setALDO4Voltage(3300);  //设置ALDO4电压值3.3V
axp2101.setPrechargeCurr(XPOWERS_AXP2101_PRECHARGE_50MA);     //设置预充电流50ma
axp2101.setChargerConstantCurr(XPOWERS_AXP2101_CHG_CUR_500MA);//设置恒流充电电流500ma
axp2101.setChargerTerminationCurr(XPOWERS_AXP2101_CHG_ITERM_50MA);//设置截止充电电流50ma
axp2101.getBattVoltage(); //获取锂电池电压

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的电源信息，如下图所示：

02_I2C_QMI8658

【程序说明】

通过驱动 QMI8658 获取姿态信息，并打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

qmi8658_set_accel_range(&qmi8658, QMI8658_ACCEL_RANGE_8G);// 设置加速度计量程为 ±8G（G=重力加速度）
qmi8658_set_accel_odr(&qmi8658, QMI8658_ACCEL_ODR_1000HZ);// 设置加速度计输出数据速率为 1000Hz（每秒1000次采样）
qmi8658_set_gyro_range(&qmi8658, QMI8658_GYRO_RANGE_512DPS);// 设置陀螺仪量程为 ±512°/s（每秒最大旋转角速度）
qmi8658_set_gyro_odr(&qmi8658, QMI8658_GYRO_ODR_1000HZ);// 设置陀螺仪输出数据速率为 1000Hz
qmi8658_set_accel_unit_mps2(&qmi8658, true);// 设置加速度计输出单位为 m/s²（米/秒²）
qmi8658_set_gyro_unit_rads(&qmi8658, true);// 设置陀螺仪输出单位为 rad/s（弧度/秒）
qmi8658_set_display_precision(&qmi8658, 4);// 设置数据输出/打印的精度为 4 位小数

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的姿态信息，如下图所示：

03_I2C_QMI8658

【程序说明】

通过驱动 PCF85063 设置时间、获取时间，并打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

pcf85063a_datetime_t datatime = {
  .year = 2026,
  .month = 1,
  .day = 1,
  .hour = 8,
  .min = 0,
  .sec = 0
};
pcf85063a_set_time_date(&pcf85063, datatime); /*设置起始时间2026/1/1 08:00:00*/
pcf85063a_get_time_date(&pcf85063, &datatime); /*获取当前的时间*/

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的 RTC 时间，如下图所示：

04_SD_Card

【程序说明】

使 SDSPI 的方式驱动 SD Card，并将 SD Card 信息打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

esp_vfs_fat_sdspi_mount(SdName_, &host, &slot_config, &mount_config, &sdCardHead); //挂载 sdcard 到 fatfs 文件系统
int SDPort_WriteFile(const char *path, const void *data, size_t data_len); //往文件写数据
int SDPort_ReadFile(const char *path, uint8_t *buffer, size_t *outLen); //从文件读取数据
int SDPort_ReadOffset(const char *path, void *buffer, size_t len, size_t offset); //带有偏移量从文件读取数据
int SDPort_WriteOffset(const char *path, const void *data, size_t len, bool append); //带有偏移量从文件写数据

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的 SD Card 信息，如下图所示：

05_WIFI_STA

【程序说明】

把开发板设置成 WIFI STA 模式，可连接 AP 路由器，并将获取 IP 地址打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

nvs_flash_init();                                     // 初始化 NVS（非易失性存储），用于保存 Wi-Fi 配置等数据
esp_netif_init();                                    // 初始化  TCP/IP 栈，网络通信所需
esp_event_loop_create_default();                     // 创建默认  事件循环，用于系统事件分发（如 Wi-Fi 事件）
esp_netif_create_default_wifi_sta();                 // 创建默  认 Wi-Fi STA（Station）接口，用于连接路由器
esp_netif_create_default_wifi_ap();                  // 创建默  认 Wi-Fi AP（Access Point）接口，用于自身提供热点
strcpy((char*)sta_config.sta.ssid, "ESP32_STA");     // 设置路由器的SSID
strcpy((char*)sta_config.sta.password, "12345678");  // 设置路由器的密码
esp_wifi_set_mode(WIFI_MODE_STA);                    // 设置ESP32 WIFI模式

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的 IP 地址，如下图所示：

06_WIFI_AP

【程序说明】

把开发板设置成 WIFI AP 模式，其余 STA 设备可连接该 AP，连接成功之后将获取设备 MAC 打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

nvs_flash_init();                                     // 初始化 NVS（非易失性存储），用于保存 Wi-Fi 配置等数据
esp_netif_init();                                    // 初始化  TCP/IP 栈，网络通信所需
esp_event_loop_create_default();                     // 创建默认  事件循环，用于系统事件分发（如 Wi-Fi 事件）
esp_netif_create_default_wifi_sta();                 // 创建默  认 Wi-Fi STA（Station）接口，用于连接路由器
esp_netif_create_default_wifi_ap();                  // 创建默  认 Wi-Fi AP（Access Point）接口，用于自身提供热点
strcpy((char*)ap_config.ap.ssid, "ESP32_AP");          // 设置 AP（热点）的 SSID 名称为 "ESP32_AP"
strcpy((char*)ap_config.ap.password, "12345678");      // 设置 AP 密码为 "12345678"（至少8位）
ap_config.ap.max_connection = 4;                       // 设置最多允许 4 台设备同时连接到 AP
ap_config.ap.authmode = WIFI_AUTH_WPA_WPA2_PSK;        // 设置认证模式为 WPA/WPA2 PSK（密码验证）
esp_wifi_set_mode(WIFI_MODE_AP);                       // 将 Wi-Fi 模式设置为 AP 模式（仅热点）
esp_wifi_set_config(WIFI_IF_AP, &ap_config);           // 应用 AP 配置，使 Wi-Fi 热点生效

【运行效果】

程序编译下载完成，打开串口监控可以看到打印输出的 MAC 地址，如下图所示：

07_Audio_Test

【程序说明】

通过驱动 ES8311 和 ES7210 Codec 芯片，实现录音、播放等功能。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

esp_err_t play_pcm_from_spiffs(uint8_t *play_buf, const char *file_path,bool *Music_flag); // 从spiffs文件系统里面读取音频数据，然后进行播放
void fac_play_read_storage(uint8_t *play_buf); // 从文件系统读取二进制录音数据，然后进行播放
void fac_rec_write_storage(uint8_t *rec_buf,size_t max_size); // 把录音数据保存到spiffs里面

【运行效果】

程序编译下载完成，可看到开发板显示内容，如下图所示：
提示
1. 点击 Recording 可录音，录音时间 3 秒
2. 点击 Play Recording 可播放录音
3. 点击 Play Music 可播放音乐
4. 点击 Stop Music 可暂停音乐

08_LVGL_V8_Test

【程序说明】

通过移植 LVGL V8 ，可帮助用户快速上手 UI 设计。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

#define Brightness_Test_EN  1 // 置 0 关闭背光测试，默认置 1 
Custom_PmicPortInit(&user_i2cbus,0x34); // 初始化电源 IC
user_display = new DisplayPort(user_i2cbus,480,480); // 初始化 屏幕
user_display->DisplayPort_TouchInit(); // 初始化 触摸
Lvgl_PortInit(*user_display); // LVGL 接口初始化

【运行效果】

程序编译下载完成，可看到开发板显示内容，如下图所示：

09_LVGL_V9_Test

【程序说明】

通过移植 LVGL V9 ，可帮助用户快速上手 UI 设计。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

#define Brightness_Test_EN  1 // 置 0 关闭背光测试，默认置 1 
Custom_PmicPortInit(&user_i2cbus,0x34); // 初始化电源 IC
user_display = new DisplayPort(user_i2cbus,480,480); // 初始化 屏幕
user_display->DisplayPort_TouchInit(); // 初始化 触摸
Lvgl_PortInit(*user_display); // LVGL 接口初始化

【运行效果】

程序编译下载完成，可看到开发板显示内容，如下图所示：

10_FactoryProgram

【程序说明】

出厂固件，用户可烧录我们提供的出厂固件，帮助用户快速了解开发板。

【硬件连接】

使用 USB 线把板子接入电脑

【运行效果】

烧录出厂固件重启之后，可看到开发板显示内容，如下图所示：
提示
1. AIChats app ：小智 AI ，可连接大模型进行语音对话
2. FacTest app ：测试板载硬件，可助力用户快速查找问题
3. GravitySphere app ：通过 IMU 实现姿态小球
4. Gallery app ：图库，可显示 sdcard 图片
5. 更多 app 开发，可通过关注 Gitee、Github 仓库连接，后续会持续更新

文档反馈

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_AXP2101_Test​

02_I2C_QMI8658​

03_I2C_QMI8658​

04_SD_Card​

05_WIFI_STA​

06_WIFI_AP​

07_Audio_Test​

08_LVGL_V8_Test​

09_LVGL_V9_Test​

10_FactoryProgram​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_AXP2101_Test

02_I2C_QMI8658

03_I2C_QMI8658

04_SD_Card

05_WIFI_STA

06_WIFI_AP

07_Audio_Test

08_LVGL_V8_Test

09_LVGL_V9_Test

10_FactoryProgram