ESP-IDF

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

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

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-S3-DualEye-LCD-1.28 开发板，需要使用 ESP-IDF V5.4.1 以上版本。

备注

以下内容以 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_Text_Number	测试文本与数字显示
02_Shapes_on_Circular	绘制图形
03_Animated_Eye1	仿真眼睛样式
04_SD_gif_show	显示 SD 卡中 gif 图片
05_Clock	时钟
06_music_player	测试板载设备功能

01_Text_Number

程序说明

本示例演示了在 LCD 双显示屏的文本与数字显示程序，核心实现“双屏同步显示固定文本+动态数字”的功能，循环显示从 00 到 99 的两位数数字，测试 LCD 屏文本以及数字显示。

硬件连接

将开发板接入电脑

代码解释

Text_Number() 主初始化函数，获取两个显示屏的活动屏幕对象并创建 ui ：
- 分别为两个屏幕调用create_screen_ui()创建 ui 界面，采用垂直布局：文本在上方，数字在下方
- lv_timer_create(update_numbers, 1000, NULL);创建 1 秒间隔的定时器用于数字更新（仅创建一次）
update_numbers()：定时器回调函数，通过定时器实现每 1000 毫秒（1 秒）调用一次 update_numbers 函数更新数字并刷新显示
- (number + 1) % 100;递增数字 (0-99 循环）
- lv_label_set_text()更新两个屏幕的数字标签显示

运行效果

LCD 屏幕显示

02_Shapes_on_Circular

程序说明

本示例实现了在 LCD 显示屏上依次显示随机颜色的正方形、三角形和圆形的效果，适用于学习 ESP32 与 LCD 显示屏交互，依次绘制随机颜色的正方形、三角形和圆形位于屏幕中心，每隔 3 秒切换，测试图形绘制稳定性。

硬件连接

将开发板接入电脑

代码解释

Shapes_on_Circular() 主初始化函数，初始化随机数生成器，创建初始形状并启动定时器，每 3 秒切换一次形状
random_color() 生成随机 RGB 颜色，为形状提供多样化的显示效果
- 使用rand() % 256生成 0-255 范围内的 RGB 分量
create_base_shape()：通用的形状创建函数，通过调整圆角程度可创建正方形和圆形
- 创建 LVGL 对象并设置指定尺寸，移除默认样式，设置背景颜色、不透明度，去除边框
- 通过radius_val参数控制圆角程度（0=直角，LV_RADIUS_CIRCLE=圆形）

运行效果

LCD 屏幕显示

03_Animated_Eye1

程序说明

本示例是基于 LVGL 图形库的双屏同步动态眼睛动画程序，实现“拟人化眼睛”的实时渲染与运动逻辑——支持两个 LCD 屏幕同步显示具有真实感的眼睛，且瞳孔会按随机目标平滑移动，模拟眼睛“自然扫视”的效果。

硬件连接

将开发板接入电脑

代码解释

Animated_Eye1() 程序入口，初始化和启动眼睛动画，通过创建定时器更新眼睛的动画效果。
- 使用固定随机种子srand(12345)确保随机行为可重复
- 创建 50 毫秒间隔的动画定时器lv_timer_create(eye_anim_timer, 50, NULL)
draw_eye() 绘制眼睛的核心，按层次绘制眼睛的各个部分（从外到内），使眼睛具有真实感
- 计算巩膜（眼白）固定中心坐标和半径（应用SCALE_FACTOR=1.5缩放）
- 根据瞳孔位置计算虹膜实际坐标，限制在MAX_OFFSET_RATIO=0.3范围内
- 计算瞳孔偏移：沿虹膜移动方向额外偏移PUPIL_OFFSET=6像素
- 分层绘制：巩膜，虹膜，瞳孔，高光
eye_anim_timer()：定时器回调函数，负责 “更新目标位置→计算瞳孔新位置→双屏同步→重绘眼睛”，实现动画效果

运行效果

LCD 屏幕显示

04_SD_gif_show

程序说明

本示例实现了通过检索 SD 卡根目录下的。gif 图片，在两个 LCD 显示屏上同步播放动画 GIF 的功能，可通过 boot 按钮控制 gif 图片切换，测试 SD 卡的读取和 LCD 屏幕图片显示功能。

硬件连接

将本工程目录下的。gif 图片拷贝到 SD 卡的根目录（可根据所需更改代码与图片的路径，名称（注意：gif 帧率需较低不然会卡卡的））
注意：连接 SD 卡，若识别失败请将 SD 卡格式化为 FAT32 格式（首次识别失败请等待一会后复位下再查看）
将开发板接入电脑

代码解释

Lvgl_Eyes() 主初始化函数，创建双屏 GIF 眼睛显示
- 初始化 FAT 文件系统lv_fs_fatfs_init()用于 SD 卡访问
- 调用find_gif_files()扫描 SD 卡根目录下的 GIF 文件
- 在两个屏幕上分别创建 GIF 显示对象并调用load_current_gif()加载并播放第一个 GIF 文件
eyes_next_gif() 切换到下一个 gif 图片。
- 循环递增current_gif_index（到达末尾后回到第一个）

运行效果

LCD 屏幕显示
点击 boot 按键切换下一张 gif 图片

05_Clock

程序说明

本示例为基于 LVGL 框架实现了一个在两个显示屏上同步显示的时钟功能，包含模拟时钟（带指针和刻度）和数字时间显示

硬件连接

将开发板接入电脑

代码解释

Clock() 主程序入口，初始化两个 LCD 显示屏的时钟，设置初始状态，并启动定时器实现动态更新。
- 分别调用create_clock_elements()在两个屏幕创建时钟画布和时间标签
- 获取当前时间并计算初始指针角度
get_current_time() 时间获取与处理，从系统获取当前时间。
draw_clock_ticks() 时钟刻度绘制，在时钟画布上绘制 12 个刻度，其中 3、6、9、12 点为更长更宽的主刻度，其余为次要刻度。
draw_clock() 完整时钟绘制，整合刻度和指针绘制，生成完整的模拟时钟画面。
- 分别调用draw_hand()绘制三根指针

运行效果

LCD 屏幕显示

06_music_player

程序说明

本示例演示了板载各个设备的功能，屏幕 2 显示 SD Card，Flash Size 等参数，屏幕 1 为音乐播放界面；另外，此示例增加语音识别功能。

硬件连接

将 SD 卡插入开发板中
将开发板接入电脑

代码解释

Driver_Init() 初始化硬件、驱动和系统所需的资源，并创建一个任务来循环执行硬件驱动
- 硬件初始化：Driver_Init()负责初始化多个硬件模块，如 I2C 总线、传感器等
- 模块化设计：初始化函数将各硬件初始化分散到不同的模块，易于维护和扩展。如果有新硬件需要支持，只需在这里添加初始化代码即可
Lvgl_Example1() 为屏幕显示 UI。

运行效果

LCD 屏幕显示

LCD 屏幕显示参数说明

参数	功能	说明
SD Card	显示 SD 卡的大小	连接 SD 卡，若识别失败请将 SD 卡格式化为 FAT32 格式（首次识别失败请等待一会后复位下再查看）
Flash Size	显示 Flash 大小	当前板载 16MB Flash
Battery Voltage	电池电压	连接电池时可检测到电池电压
Wireless scan	显示扫描到的 WIFI 个数	扫描结束会在末尾显示 ..OK

页面 2 为播放 SD 卡根目录下的 mp3 音频的 UI 页面
本程序默认启用语音识别，唤醒词为 “hi esp”，唤醒后，背光变暗后即可说出指令（背光未变暗则表示未被唤醒，识别要求较为严格，发音需要标准，语速放缓）
以下提供几种格式的 MIC 测试音频（请注意，每次 hi esp 唤醒失败的话请重新将音频调至该次唤醒词播放处重新播放）
请不要在使用喇叭播放音频时进行语音识别
测试音频中之所以播放两次唤醒词，是由于当前固件版本首次唤醒需要聚焦设备（比喻），并且当前固件并不允许关闭该功能
```
  // 指令
  Turn on the backlight
  Turn off the backlight
  Backlight is brightest
  Backlight is darkest
```
注意：当前示例仅在播放音频前可使用语音识别功能

切换为中/英文识别模型

环境初始状态默认为英文识别环境，按照以下步骤可切换为中文识别模型或英文识别模型
- 【切换为中/英文识别模型】
  - 若工程中存在以下两个文件，则删除这两个文件
  - 进入文件 sdkconfig.defaults，找到此处。
    - 使用 "#" 注释①处则切换为英文识别模型
    - 使用 "#" 注释②处则切换为中文识别模型

生成语音控制指令

环境准备

检查电脑是否有 Python 环境
打开命令行：Win + R -> 输入 cmd
- ①. 输入 python --version 出现 Python 版本号，则表示已安装
- ②. 输入 where python 查看 Python 安装位置
- C 盘下的 Python 环境为安装 VS Code 时自动安装的 Python 环境
- E 盘下是以下步骤用到的 Python 环境

注意

若没有安装环境请查看 Python 环境安装教程，已安装请继续

命令行输入 pip install g2p_en 安装 g2p_en 包
安装资源包放在对应用户的 C:\Users\用户名、AppData\Roaming 路径下，双击解压文件
命令行输入 pip install pypinyin 安装 pypinyin 库

生成中文拼音

下载中文指令生成文件
命令行切换路径至中文指令生成文件夹下（路径因人而异，以下仅参考）
```
cd /d E:\download\Generate_Chinese_command
```

命令行执行 multinet_pinyin.py 生成中文拼音

python multinet_pinyin.py "要转为拼音的中文"

例：

python multinet_pinyin.py "你好微雪电子"

生成英文音素

下载英文指令生成文件
命令行切换路径至英文指令生成文件夹下（路径因人而异，以下仅参考）
```
cd /d E:\download\Generate_English_command
```

命令行执行 gen_sr_commands.py 生成音素指令

python gen_sr_commands.py "要转为音素的英文"

例：

python gen_sr_commands.py "hello waveshare"

指令修改

Arduino 下
ESP-IDF 下
- 中文指令
- 英文指令

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_Text_Number​

程序说明​

硬件连接​

运行效果​

02_Shapes_on_Circular​

程序说明​

硬件连接​

运行效果​

03_Animated_Eye1​

程序说明​

硬件连接​

运行效果​

04_SD_gif_show​

程序说明​

硬件连接​

运行效果​

05_Clock​

程序说明​

硬件连接​

运行效果​

06_music_player​

程序说明​

硬件连接​

运行效果​

切换为中/英文识别模型​

生成语音控制指令​

环境准备​

生成中文拼音​

生成英文音素​

指令修改​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_Text_Number

程序说明

硬件连接

运行效果

02_Shapes_on_Circular

程序说明

硬件连接

运行效果

03_Animated_Eye1

程序说明

硬件连接

运行效果

04_SD_gif_show

程序说明

硬件连接

运行效果

05_Clock

程序说明

硬件连接

运行效果

06_music_player

程序说明

硬件连接

运行效果

切换为中/英文识别模型

生成语音控制指令

环境准备

生成中文拼音

生成英文音素

指令修改