ESP-IDF

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

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

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-S3-ePaper-Driver-Board 开发板，需要使用 ESP-IDF V5.5.0 以上版本。

备注

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

版本选择

此部分图示以安装 ESP-IDF V5.2.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 示例程序位于示例程序包的 ESP-IDF 目录中。

示例程序	基础例程说明
01_ADC_Test	获取锂电池的电压值
02_Mic_test	扬声器播放麦克风录音
03_Music	挂载 SD 卡，读取播放 SD 卡中的音乐
04_E-Paper_Example	墨水屏示例程序
05_SD_Test	读取 SD 卡显示图片
06_xiaozhi-esp32	小智 AI 应用

01_ADC_Test

【程序说明】

通过 GPIO 连接的模拟量电压经过 ADC 转换成数字量，然后通过计算得到实际的锂电池电压，并打印到终端。

【硬件连接】

使用 USB 线把板子接入电脑

【代码分析】

adc_bsp_init(void)：初始化 ADC1，包括创建 ADC 单次触发单元并配置 ADC1 的通道 7。
adc_get_value(float *value,int *data)：读取 ADC1 通道 7 的值，并根据参考电压和分辨率计算出对应的电压值存储在传入的指针指向的位置，如果读取失败则存储 0。
adc_example(void* parameter)：初始化 ADC1 后，创建一个 ADC 任务，该任务每隔 1 秒读取一次 ADC 的值，通过读取的 ADC 原始值计算出系统的电压。

【运行效果】

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

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_E-Paper_Example

程序说明

本示例为 13.3 寸 E6 墨水屏 ESP-IDF 本地例程，实现电子纸初始化清屏，显示图片，绘制基础图形、文字。

硬件连接

将开发板接入电脑

代码解释

显示预设图片：

#if 1
  EPD_Display(Image6color);
  vTaskDelay(pdMS_TO_TICKS(3000));
#endif

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

#if 1
  Paint_NewImage(Image_Mono, EPD_WIDTH, EPD_HEIGHT, 90, EPD_WHITE);
  Paint_SetScale(6);
  printf("SelectImage:Image\r\n");
  Paint_SelectImage(Image_Mono);
  Paint_Clear(EPD_WHITE);

  Paint_DrawPoint(10, 80, EPD_RED, DOT_PIXEL_1X1, DOT_STYLE_DFT);
  Paint_DrawPoint(10, 90, EPD_BLUE, DOT_PIXEL_2X2, DOT_STYLE_DFT);
  Paint_DrawPoint(10, 100, EPD_GREEN, DOT_PIXEL_3X3, DOT_STYLE_DFT);
  Paint_DrawLine(20, 70, 70, 120, EPD_YELLOW, DOT_PIXEL_1X1, LINE_STYLE_SOLID);
  Paint_DrawLine(70, 70, 20, 120, EPD_YELLOW, DOT_PIXEL_1X1, LINE_STYLE_SOLID);
  Paint_DrawRectangle(20, 70, 70, 120, EPD_BLACK, DOT_PIXEL_1X1, DRAW_FILL_EMPTY);
  Paint_DrawRectangle(80, 70, 130, 120, EPD_BLACK, DOT_PIXEL_1X1, DRAW_FILL_FULL);
  Paint_DrawCircle(45, 95, 20, EPD_BLACK, DOT_PIXEL_1X1, DRAW_FILL_EMPTY);
  Paint_DrawCircle(105, 95, 20, EPD_WHITE, DOT_PIXEL_1X1, DRAW_FILL_FULL);
  Paint_DrawLine(85, 95, 125, 95, EPD_YELLOW, DOT_PIXEL_1X1, LINE_STYLE_DOTTED);
  Paint_DrawLine(105, 75, 105, 115, EPD_YELLOW, DOT_PIXEL_1X1, LINE_STYLE_DOTTED);
  Paint_DrawString_CN(10, 130, "你好 abc", &Font16_UTF8, EPD_BLACK, EPD_WHITE);
  Paint_DrawString_CN(10, 170, "微雪电子", &Font16_UTF8, EPD_WHITE, EPD_BLACK);
  Paint_DrawNum(10, 10, 123456789, &Font12, EPD_BLACK, EPD_WHITE);
  Paint_DrawNum(10, 40, 987654321, &Font12, EPD_WHITE, EPD_BLACK);
  Paint_DrawString_EN(145, 0, "Waveshare", &Font16, EPD_BLACK, EPD_WHITE);
  Paint_DrawString_EN(145, 35, "Waveshare", &Font16, EPD_GREEN, EPD_WHITE);
  Paint_DrawString_EN(145, 70, "Waveshare", &Font16, EPD_BLUE, EPD_WHITE);
  Paint_DrawString_EN(145, 105, "Waveshare", &Font16, EPD_RED, EPD_WHITE);
  Paint_DrawString_EN(145, 140, "Waveshare", &Font16, EPD_YELLOW, EPD_WHITE);

  printf("EPD_Display\r\n");
  EPD_Display(Image_Mono);
  vTaskDelay(pdMS_TO_TICKS(3000));
#endif

运行效果

屏幕刷新初始化清屏，显示图片，绘制基础图形、文字

05_SD_Test

【程序说明】

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

【硬件连接】

使用 USB 线把板子接入电脑
将保存有图片的 bmp 文件夹放入 SD 卡根目录，插入 SD 卡模块

【代码分析】

_sdcard_init：sd 卡初始化
GUI_ReadBmp_RGB_6Color("/sdcard/bmp/13in3E.bmp", 0, 0);：图片解码

【运行效果】

串口打印 SD 信息
读取显示 sd 卡图片

06_xiaozhi-esp32

【硬件连接】

使用 USB 线把板子接入电脑
将 SD 卡文件夹所有文件拷贝到 sdcard 上，插入 SD 卡模块
插入 SD 卡模块后再上电或复位设备

【程序说明】

根据自己的方式先下载程序，解压后将 sdcard 目录下的所有文件拷贝到 SD 卡根目录
程序包含三种工作模式：
- 模式 1：基础图片显示模式
- 模式 2：局域网图片服务器模式
- 模式 3：AI 对话模式
默认工作模式为：基础模式（模式 1）
如果未插入 SD 卡，部分功能会受限，设备会刷新内置图片或显示提示信息

模式切换

长按 BOOT 按键进入模式选择，设备会语音播报“模式选择”
单击 BOOT 按键依次切换模式，设备会播报当前选择的模式
再次长按 BOOT 按键确认并进入当前选择的模式

模式 1

将需要显示的图片放入 SD 卡的 img 目录
支持显示 1600x1200 或 1200x1600 分辨率，位深 24 位 BMP，JPG，PNG 格式的图片
单击 BOOT 按键显示或切换 img 目录下的图片
如果没有插入 SD 卡，或者 SD 卡 img 目录下没有可读取图片，设备会刷新内置图片

模式 2

模式 2 支持两种网络方式：AP 模式和 STA 模式。

AP 模式

设备会开启 WiFi 热点：
- SSID：esp_network
- 密码：1234567890
手机或电脑连接该热点后，访问：
- http://192.168.4.1/index.html
在网页中可以选择、预览并推送图片到墨水屏显示

STA 模式

STA 模式会连接模式 3 中小智配网保存的路由器 WiFi
手机或电脑需要连接到同一个路由器 WiFi
设备连接成功后，墨水屏会显示两个访问地址：
- mDNS 地址：http://esp32-s3-photopainter.local/index.html
- IP 地址：例如 http://192.168.x.x/index.html
如果 .local 地址无法打开，请优先使用屏幕上显示的 IP 地址访问
如果未配置 WiFi 或连接失败，屏幕会显示对应提示；可双击 BOOT 按键重置为 AP 模式

注意：STA 模式下设备不会再开启 esp_network 热点，而是连接已保存的路由器 WiFi。

模式 3

首次进入模式三会有一个配网的过程，语音会播报"进入配网模式"，这个时候使用手机连接 Xiaozhi-xxx(xxx 表示不固定的）
配网成功之后，进入小智控制台，添加对应的设备
初始化完成后，通过"你好，小智"唤醒词唤醒
唤醒之后即可正常对话
可以通过对话，获取 sd 卡 img 目录的图片数量并显示
关于 AI 生成图片的使用，比如可以说"帮我生成一张月球的图片"，如果需要使用这个功能，需要配置火山引擎，具体的配置参考火山引擎文生图配置

火山引擎文生图配置

首先需要得是获取密钥、模型名称、URL，目前使用得是测试模型，后续会停掉的，用户需要自己配置模型，相关代码段和 config.txt 文件里面相关配置如下：
先进入火山引擎控制台
创建对应的模型，记得模型不要选错，如图：
复制对应的 key、model、url，如图
把复制好的 url、model、key 粘贴到 sdcard->img 目录下的 config.txt 文件对应键值（步骤 1 图 2）即可（新用户可以免费领取 Tokens）

文档反馈

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_ADC_Test​

02_Mic_test​

程序说明​

硬件连接​

运行效果​

03_Music​

程序说明​

硬件连接​

运行效果​

04_E-Paper_Example​

程序说明​

硬件连接​

运行效果​

05_SD_Test​

06_xiaozhi-esp32​

模式切换​

模式 1​

模式 2​

AP 模式​

STA 模式​

模式 3​

火山引擎文生图配置​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_ADC_Test

02_Mic_test

程序说明

硬件连接

运行效果

03_Music

程序说明

硬件连接

运行效果

04_E-Paper_Example

程序说明

硬件连接

运行效果

05_SD_Test

06_xiaozhi-esp32

模式切换

模式 1

模式 2

AP 模式

STA 模式

模式 3

火山引擎文生图配置