ESP-IDF

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

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

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-C6-GEEK 开发板，需要使用 ESP-IDF V5.5.0 以上版本。

备注

以下内容以 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_E-Paper_Example	3.97inch e-Paper 墨水屏幕示例程序
02_Mic_test	扬声器播放麦克风录到的声音
03_Music	挂载 SD 卡，读取播放 SD 卡中的音乐
04_SD_Test	挂载 SD 卡，读取 SD 卡中的图片并刷新显示
05_QMI8658A	六轴陀螺仪例程
06_I2C_PCF85063	RTC 例程
07_I2C_SHTC3	温湿度传感器例程
08_ESP32-S3_e-Paper-3.97	集成了文件浏览、时钟、日历、闹钟、天气、网络配置、音频播放、电子阅读器功能

01_E-Paper_Example

程序说明

本示例演示了 3.97 寸墨水屏 ESP-IDF 本地例程，实现墨水屏初始化清屏，显示图片，绘制基础图形、文字，局部刷新动态显示时间。

硬件连接

将开发板接入电脑

代码解释

显示预设图片：

  #if 1
    ESP_LOGI(TAG,"2.show BMP");
    EPD_Init_Fast();
    EPD_Display(gImage_image);
    vTaskDelay(pdMS_TO_TICKS(2000));
 #endif

绘制基础图形、中英文文字、数字，并刷新显示：

  #if 1
    ESP_LOGI(TAG,"3.Paint_NewImage");
    EPD_Init();
    Paint_NewImage(Image_Mono, EPD_WIDTH, EPD_HEIGHT, 0, WHITE);
    Paint_SelectImage(Image_Mono);
    Paint_Clear(WHITE);
    // Drawing on the image
    Paint_DrawPoint(5, 10, BLACK, DOT_PIXEL_1X1, DOT_STYLE_DFT);
    Paint_DrawPoint(5, 25, BLACK, DOT_PIXEL_2X2, DOT_STYLE_DFT);
    Paint_DrawPoint(5, 40, BLACK, DOT_PIXEL_3X3, DOT_STYLE_DFT);
    Paint_DrawPoint(5, 55, BLACK, DOT_PIXEL_4X4, DOT_STYLE_DFT);

    Paint_DrawLine(20, 10, 70, 60, BLACK, DOT_PIXEL_1X1, LINE_STYLE_SOLID);
    Paint_DrawLine(70, 10, 20, 60, BLACK, DOT_PIXEL_1X1, LINE_STYLE_SOLID);
    Paint_DrawLine(170, 15, 170, 55, BLACK, DOT_PIXEL_1X1, LINE_STYLE_DOTTED);
    Paint_DrawLine(150, 35, 190, 35, BLACK, DOT_PIXEL_1X1, LINE_STYLE_DOTTED);

    Paint_DrawRectangle(20, 10, 70, 60, BLACK, DOT_PIXEL_1X1, DRAW_FILL_EMPTY);
    Paint_DrawRectangle(85, 10, 130, 60, BLACK, DOT_PIXEL_1X1, DRAW_FILL_FULL);

    Paint_DrawCircle(170, 35, 20, BLACK, DOT_PIXEL_1X1, DRAW_FILL_EMPTY);
    Paint_DrawCircle(170, 85, 20, BLACK, DOT_PIXEL_1X1, DRAW_FILL_FULL);

    Paint_DrawNum(5, 180, 123456789, &Font24, BLACK, WHITE);
    Paint_DrawString_CN(5, 100,"你好 abc", &Font16_UTF8, BLACK, WHITE);
    Paint_DrawString_CN(5, 130, "微雪电子", &Font24_UTF8, WHITE, BLACK);

    EPD_Display_Base(Image_Mono);
    vTaskDelay(pdMS_TO_TICKS(2000));
    #endif

运行效果

墨水屏刷新显示

02_Mic_test

程序说明

演示如何获取麦克风的数据，然后再通过扬声器播放。

硬件连接

将开发板接入电脑

代码分析

i2c_master_Init(); ：初始化 I2C 总线。
user_ui_init();：初始化全局 ui。
user_button_init();：初始化 audio 接口。

运行效果

屏幕无显示效果
长按 BOOT 按键即可进入录音模式，对着 MIC 说话，3 秒后自动结束
单击 BOOT 按键，播放刚刚录的声音，（如果没有录音的情况下，播放的声音会很刺耳）
串口打印：

03_Music

程序说明

挂载 SD 卡，读取播放 SD 卡中的音频

硬件连接

将开发板接入电脑
喇叭接入 SPK 接口

代码分析

_sdcard_init(); ：初始化 SD 卡并读取 SD 卡音频文件。
i2c_master_init();：初始化 I2C 总线，为 ES8311 音频编解码器的配置指令传输提供通信链路。
audio_player_play(audio_fp);：启动音频播放器，读取打开的 MP3 文件并通过 ES8311 驱动扬声器播放。

运行效果

屏幕无显示效果
喇叭播放音频

04_SD_Test

程序说明

该例程通过读取 SD 卡中的 BMP 图片并在墨水屏上刷新显示

硬件连接

将开发板接入电脑
将当前程序 bmp 文件夹放入 SD 卡根目录，插入 SD 卡模块

代码分析

_sdcard_init(); ：初始化 SD 卡并读取 SD 卡音频文件。
epaper_port_init();：初始化墨水屏底层硬件端口（引脚、通信总线等）
EPD_Init();/EPD_Clear();：初始化墨水屏驱动参数，清屏显示白色背景
GUI_ReadBmp("/sdcard/bmp/100x100.bmp", 50, 50);/EPD_Display_Fast(BlackImage);：读取 SD 卡中 BMP 图片，快速刷新显示图片
GUI_ReadBmp_4Gray("/sdcard/bmp/3in97_4Gray.bmp", 0, 0);/EPD_Display_4Gray(BlackImage);：读取并显示 SD 卡中 4 灰度 BMP 图片

运行效果

读取显示 sd 卡图片

05_QMI8658A

程序说明

该例程通过读取 SD 卡中的 BMP 图片并在墨水屏上刷新显示

硬件连接

将开发板接入电脑
将当前程序 bmp 文件夹放入 SD 卡根目录，插入 SD 卡模块

代码分析

epaper_port_init();/EPD_Init();/EPD_Clear();绘制数值后调用 EPD_Display_Partial 局部刷新墨水屏：初始化墨水屏底层硬件端口、驱动参数，清屏显示白色背景
i2c_master_init();：初始化 I2C 总线，为 QMI8658 传感器的配置和数据读取提供通信链路
xTaskCreate(qmi8658_test_task, "qmi8658_test_task", 4096, i2c_bus_handle, 5, NULL);：创建 FreeRTOS 任务执行 QMI8658 传感器数据读取逻辑
qmi8658_is_data_ready(&dev, &ready);：检测传感器数据是否就绪，仅当数据就绪时读取数据。
qmi8658_read_sensor_data(&dev, &data);：读取传感器的加速度、陀螺仪、温度、时间戳数据，串口打印数据
draw_qmi8658_data_to_epaper(&data);：绘制数值后调用EPD_Display_Partial局部刷新显示数据

运行效果

墨水屏局部刷新显示六轴陀螺仪传感器数据

06_I2C_PCF85063

程序说明

该示例使用板载 PCF85063 RTC 芯片，实现 3.97 寸墨水屏结合 I2C 接口 RTC 实时时钟模块动态显示功能

硬件连接

将开发板接入电脑

代码分析

epaper_port_init();/EPD_Init();/EPD_Clear();绘制数值后调用 EPD_Display_Partial 局部刷新墨水屏：初始化墨水屏底层硬件端口、驱动参数，清屏显示白色背景
i2c_master_init();：初始化 I2C 总线，为 PCF85063 RTC 模块的配置和时间读取提供通信链路。
PCF85063_init();：初始化 PCF85063 RTC 模块，完成时钟寄存器默认配置。
PCF85063_GetTime();/PCF85063_SetTime();：读取 RTC 当前时间，设置默认时间。
xTaskCreate(rtc_test_task, "rtc_display", 4096, NULL, 5, NULL);：创建 FreeRTOS 任务执行 RTC 时间读取和显示逻辑
display_time_on_epaper()：绘制数值后调用EPD_Display_Partial局部刷新显示数据

运行效果

墨水屏局部刷新显示时间

07_I2C_SHTC3

程序说明

该示例使用板载 SHTC3 温湿度传感器，实现 3.97 寸墨水屏动态显示温湿度数据功能

硬件连接

将开发板接入电脑

代码分析

epaper_port_init();/EPD_Init();/EPD_Clear();绘制数值后调用 EPD_Display_Partial 局部刷新墨水屏：初始化墨水屏底层硬件端口、驱动参数，清屏显示白色背景
i2c_master_init();：初始化 I2C 总线。
i2c_shtc3_init();：初始化 SHTC3 温湿度传感器模块。
xTaskCreatePinnedToCore(i2c_SHTC3_loop_task, "i2c_SHTC3_loop_task", 3 * 1024, NULL , 2, NULL,0);：创建 FreeRTOS 任务
i2c_SHTC3_loop_task()：获取温湿度数值并打印，调用EPD_Display_Partial局部刷新显示数据

运行效果

墨水屏局部刷新显示温湿度

08_ESP32-S3_e-Paper-3.97

程序说明

该示例集成了文件浏览、时钟、日历、闹钟、天气、网络配置、音频播放、电子阅读器 8 大核心功能，实现墨水屏菜单化交互和按钮控制

硬件连接

使用 USB 线将开发板接入电脑
将示例程序下的 SD 卡文件夹所有文件，存入 SD 卡根目录下
插入 SD 卡模块

电池续航

时钟模式下 1500mA 电池可工作 15 天以上

代码分析

app_main()中完成 NVS、SD 卡、I2C 外设（传感器 / 时钟 / 音频）、按键、墨水屏的初始化，从 NVS 加载配置（WiFi 使能、工作模式），根据模式创建对应任务；
void user_Task(void *arg)负责绘制墨水屏主菜单（8 个功能图标 + 文字）、响应按键事件（上下选择、确认进入子页、全局刷新、关机）、管理墨水屏低功耗（5 秒无操作睡眠、10 分钟无操作软关机）、刷新顶部状态栏（时间 / 电量 / WiFi 状态）；
file_browser_task(); 文件浏览模块
page_clock_show(); 时钟模块
page_calendar_show(); 日历模块
page_alarm_menu(); 闹钟模块
page_weather_city_select(); 天气模块
page_handle_network_key_event(); 网络配置模块
page_audio_main(); 音频播放模块
page_fiction_file(); 电子阅读器模块

运行效果

烧录程序完成后进入配置网络界面，通过连接墨水屏显示的 wifi 名称进行网络配置
网络配置完成进入主页面，通过拨轮按钮与 BOOT 和 PWR 侧边按钮控制，60 秒无操作墨水屏自动睡眠，10 分钟无操作软关机

文件浏览模块
- 读取 SD 卡所有目录文件，仅可打开文件夹、txt 文本、音频文件，其他格式文件无法打开
- 上下拨轮（↑↓）选择文件 / 目录，单击确认进入 / 打开
- 双击确认 / Boot 返回上一级目录，长按中间拨轮执行全局刷新
时钟模块
- 刷新显示温湿度，时间，电池电量
- 支持时区选择功能：单击确认进入时区选择界面，墨水屏显示操作提示，上下拨轮↑↓选择时区、单击确认生效
日历模块
- 刷新显示日历（基于国内 API，国外使用加载较慢），包含公历日期、农历日期 / 节气 / 节日，当前日期高亮显示
- 支持手动刷新：长按中间拨轮重新从网络获取最新日期数据，每天自动更新一次
- 低功耗与唤醒规则：10 分钟无操作自动关机，默认每一小时 RTC 唤醒一次；若检测到当前页面有闹钟设置，改为每分钟唤醒一次
闹钟模块
- 闹钟模块主界面，支持最多 5 组闹钟设置
- 删除闹钟后时间默认复位为 00:00 且状态为关闭，单击确认进入闹钟编辑模式，上下拨轮↑↓选择需编辑的内容（时 / 分 / 开关）
- 时 / 分编辑：单击确认进入数值调节，上下拨轮↑↓按键可单次调节也可长按连续调节；开关编辑：单击确认切换一次开启 / 关闭状态，双击确认 / Boot 退出编辑模式
- 闹铃触发：设置的闹钟时间到后自动播放内置音频，按下任一按键停止播放，双击确认 / Boot 退出闹钟模块返回主页面
天气模块（需要先开启 WIFI 连接，使用国内天气软件 API 与码表，国外适配中）
- 天气模块主界面，显示日期，温湿度，和近 4 天的天气信息
- 每天 4 个定点（4 点、9 点、14 点、20 点）自动更新天气数据，长按拨轮可手动重新从网络获取最新天气
- 10 分钟无操作自动关机，默认每一小时 RTC 唤醒一次；若检测到当前页面有闹钟设置，改为每分钟唤醒一次
- 天气模块的图标文件存储目录在：sdcard\Weather_img\Weather_img , 支持自行添加 / 修改天气图片：
  - 在 sdcard\Weather_img\Weather_img 文件夹下增加新的天气图片
  - 打开 Weather.txt，增加要显示的名称和对应图片
网络配置模块
- 支持 WiFi 开启 / 关闭、重新配网操作，WiFi 关闭状态下仅显示「打开 WiFi」和「返回主菜单」；WiFi 开启状态下显示「关闭 WiFi」「重新配网」「返回主菜单」
- 选择配网后进入 STA 模式，该模式下不触发自动关机，仅墨水屏进入睡眠状态，ESP32 持续工作；将设备连接墨水屏显示的 WiFi 名称，完成配网
- 尝试连接已配置 WiFi30 秒，期间无法其他操作，连接失败则退出配网；连接成功后自动获取 IP 地址，墨水屏提示配网成功
音频播放模块
- 支持三种音频模式：内置音频、TF 卡音频、录音，上下拨轮↑↓选择模式，单击确认进入；TF 卡音频读取 SD 卡根目录 music 文件夹内文件，录制的音频文件也自动保存至该文件夹
- 内置音频单击确认直接播放，录音模式单击确认直接开始录音，TF 卡音频模式下单击确认选择并播放音频文件，无声音调节功能
- 选中音频文件后单击确认进入操作选择界面，双击确认 / Boot 返回上一级，长按中间拨轮执行全局刷新
电子阅读器模块
- 电子阅读器模块主界面
- 读取 SD 卡根目录 fiction 文件夹内的 txt 文本文件，上下拨轮↑↓选择文件，单击确认开始阅读，阅读时上下拨轮↑↓控制翻页
- 双击拨轮进入字体选择界面，单击确认选择字体并生效；
- 单击拨轮进入书签管理界面，再次单击执行书签操作，双击确认添加书签，阅读进度与书签自动保存至 SD 卡 bookmarks 文件夹
系统设置模块
- 进入方式：在主页面长按 Boot 按键进入设置界面，上下拨轮↑↓选择功能项，单击确认查看，双击确认 / Boot 返回主页面
- 当前支持两大功能：内存展示（显示设备当前内存情况）、QMI8658 六轴状态展示（实时显示加速度、角速度等数据）
- 支持全局刷新：长按中间拨轮执行墨水屏全局刷新，遵循 60 秒睡眠、10 分钟关机的低功耗规则
系统开关机
- 在主页面双击 boot 按键，系统关机
- 长按 Power 按钮 4 秒，系统开机，墨水屏刷新显示