ESP-IDF
本章节包含以下部分，请按需阅读：
在运行示例前，请先确认以下条件已经满足：
- 已准备 ESP32-S3-Touch-AMOLED-2.16 开发板。
- 已使用 USB 数据线连接开发板和电脑。
- 已安装 ESP-IDF 开发环境，推荐使用 ESP-IDF v5.5 或更高版本。
- 已安装 VS Code 和 ESP-IDF 插件，或已经可以在命令行中正常使用
idf.py。 - 已获取本产品的示例代码。
ESP-IDF 入门教程
初次接触 ESP32 ESP-IDF 开发，想要快速上手？我们为您准备了一套通用的 入门教程。
- 第0节 认识 ESP32
- 第1节 搭建环境
- 第2节 运行实例
- 第3节 创建项目
- 第4节 使用组件
- 第5节 调试程序
- 第6节 FreeRTOS
- 第7节 驱动外设
- 第8节 Wi-Fi 编程
- 第9节 BLE 编程
请注意：该教程使用 ESP32-S3-Zero 作为教学示例，所有硬件代码均基于其引脚布局。在动手实践前，建议您对照手中的开发板引脚图，确认引脚配置无误。
配置 ESP-IDF 开发环境
对于 ESP32-S3-Touch-AMOLED-2.16 开发板，需要使用 ESP-IDF V5.5 以上版本。
以下内容以 Windows 系统为例，使用 VS Code + ESP-IDF 扩展 的方式进行开发。Mac/Linux 用户请参考 官方说明。
此部分图示以安装 ESP-IDF V5.5.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_AXP2101 | 通过移植后的 XPowersLib 驱动 AXP2101 获取电源相关数据 |
| 02_lvgl_demo_v9 | LVGL 演示 |
| 03_esp-brookesia | 展示完整手机风格 UI 系统，包含状态栏、导航栏、应用启动器和手势交互等组件 |
| 04_Immersive_block | 通过 QMI8658 六轴传感器采集加速度数据，驱动 LVGL 图形库渲染的随机几何图形跟随设备倾斜方向移动 |
| 05_Spec_Analyzer | 展示实时音频频谱可视化分析仪，以 64 条彩色对称频谱条 + 峰值跟踪的形式，直观呈现音频的频率分布 |
本产品的 ESP-IDF 示例主要覆盖以下硬件资源：
| 硬件资源 | 作用 | 相关示例 |
|---|---|---|
| ESP32-S3 主控 | 运行 ESP-IDF 应用程序 | 全部示例 |
| AMOLED 显示屏 | 显示 LVGL 图形界面、动画和频谱 | 02_lvgl_demo_v9、03_esp-brookesia、04_Immersive_block、05_Spec_Analyzer |
| 触摸功能 | 用于 UI 交互 | 02_lvgl_demo_v9、03_esp-brookesia |
| AXP2101 PMU | 电源管理、电压轨配置、电源状态读取 | 01_AXP2101 |
| QMI8658 IMU | 加速度、姿态数据读取 | 04_Immersive_block |
| 音频输入 | 音频采样和频谱分析 | 05_Spec_Analyzer |
如果是第一次使用板子，建议按以下顺序运行：
01_AXP2101：确认 PMU 和 I2C 通信正常。02_lvgl_demo_v9：确认显示屏、触摸和 LVGL 基础功能正常。04_Immersive_block：确认 IMU 和屏幕动态刷新正常。05_Spec_Analyzer：确认音频采样、DSP 和显示刷新正常。03_esp-brookesia：体验更完整的手机风格 UI 示例。
1. 目录结构
当前 ESP-IDF 示例目录包含以下工程：
examples/ESP-IDF-v5.5
├── 01_AXP2101
├── 02_lvgl_demo_v9
├── 03_esp-brookesia
├── 04_Immersive_block
└── 05_Spec_Analyzer
每个子目录都是一个独立的 ESP-IDF 工程。编译程序时需要进入具体示例目录后再执行编译、烧录和监视命令。
典型工程结构如下：
示例工程
├── CMakeLists.txt
├── main
│ ├── CMakeLists.txt
│ ├── idf_component.yml
│ └── main.c / main.cpp
├── components
│ └── 本示例依赖的本地组件
├── partitions.csv
└── sdkconfig.defaults
各目录含义：
| 目录或文件 | 说明 |
|---|---|
main/main.c 或 main/main.cpp | 应用入口，理解示例时应优先查看这里 |
components | 本地组件目录，包含 BSP、驱动、UI 框架或第三方库 |
idf_component.yml | 组件依赖声明，ESP-IDF 会根据该文件下载依赖 |
sdkconfig.defaults | 示例默认配置 |
partitions.csv | Flash 分区表，部分图形或音频示例需要较大的应用分区 |
CMakeLists.txt | ESP-IDF 工程构建配置 |
2. 通过 VS Code 运行示例
如果使用 VS Code，建议按以下步骤运行示例：
-
打开 VS Code。
-
选择
File ---> Open Folder，打开某一个示例工程目录，例如：examples/ESP-IDF-v5.5/02_lvgl_demo_v9
在构建和烧录之前，我们需要设置目标硬件和连接方式。VS Code ESP-IDF 扩展在底部状态栏提供了 集成工具栏，可以直接在工具栏中进行设置。
-
点击
选择烧录方式：选择 UART 接口。
-
点击
选择串口：将 ESP32 开发板连接到电脑。点击端口号，从列表中选择开发板对应的串口。
-
提示：如果不确定是哪一个，可以拔下开发板再插上，看看哪个端口号是新出现的。
-
故障排查：如果未能找到新端口，请尝试手动进入下载模式：按住 “BOOT” 按钮，同时插入 USB 数据线，然后再松开按钮。 之后再次检查，即可找到正确的端口。
-
-
点击
选择目标设备：点击芯片名称（如 esp32s3），选择与开发板完全匹配的芯片型号。
设置目标设备时，ESP-IDF 需要配置相应的工具链和库，此过程可能需要一些时间，请耐心等待其完成。
更多详情可查阅 官方文档。
-
构建：用 CMake/Ninja 将项目及各组件编译、链接成可执行固件。
点击
按钮即可编译固件。在此步骤会生成：
- 应用程序 ELF 文件（用于调试）
- 可烧录的二进制文件（.bin）
- 引导加载程序（bootloader.bin）
- 分区表（partition-table.bin）
详细说明请参考：ESP-IDF 构建系统
-
烧录：将构建好的固件通过串口等方式写入目标 ESP32 开发板的闪存（Flash）中。
点击
按钮烧录固件。烧录时，ESP-IDF 扩展会自动调用 esptool.py 工具来完成实际的通信和写入操作。终端会显示烧录进度。
-
监视：打开 IDF 监视器 查看设备运行日志与打印输出，是调试程序、观察运行状态的重要手段。
点击
即可监视 ESP32 串口。使用快捷键 Ctrl + ] 可以退出 ESP-IDF 监视器。
-
也可以点击
一键自动依次执行构建、烧录和监视这三个步骤。
正常情况下，烧录完成后开发板会自动复位并运行当前示例。
3. 通过命令行运行示例
如果使用命令行，进入示例目录后执行以下命令。
以 02_lvgl_demo_v9 为例：
cd examples/ESP-IDF-v5.5/02_lvgl_demo_v9
idf.py set-target esp32s3
idf.py build
idf.py -p PORT flash monitor
请将 PORT 替换为实际串口名称，例如：
idf.py -p COM8 flash monitor
或：
idf.py -p /dev/ttyUSB0 flash monitor
也可以使用一条命令完成编译、烧录和监视：
idf.py -p PORT flash monitor
退出串口监视器：
Ctrl + ]
如果切换了示例工程、ESP-IDF 版本或配置，建议先清理构建目录：
idf.py fullclean
idf.py set-target esp32s3
idf.py -p PORT flash monitor
4. 示例说明
01_AXP2101
【功能说明】
该示例用于验证 AXP2101 电源管理芯片是否可以通过 I2C 正常访问，并完成 PMU 初始化和周期性电源状态处理。
主要作用：
- 初始化 I2C Master。
- 添加 AXP2101 I2C 设备，默认设备地址为
0x34。 - 调用
pmu_init()初始化 PMU。 - 创建电源处理任务，周期性调用
pmu_isr_handler()。
【代码入口】
主要入口文件：
01_AXP2101/main/main.cpp
建议优先查看：
| 函数 | 作用 |
|---|---|
app_main() | 应用入口，完成 I2C 初始化、PMU 初始化和任务创建 |
i2c_init() | 使用 ESP-IDF 新版 I2C Master API 初始化 I2C |
pmu_register_read() | PMU 寄存器读取接口 |
pmu_register_write_byte() | PMU 寄存器写入接口 |
pmu_hander_task() | 周期性处理 PMU 状态 |
【正常运行现象】
串口日志中应能看到 I2C 初始化成功、PMU 初始化相关信息。如果 I2C 或 PMU 通信异常，通常会看到 PMU READ FAILED! 或 PMU WRITE FAILED! 等错误。
【常见排查】
| 现象 | 可能原因 | 建议处理 |
|---|---|---|
| 提示 PMU 读取失败 | I2C 引脚配置错误、PMU 未响应 | 检查 menuconfig 中 PMU I2C SDA/SCL 配置 |
| 编译失败 | ESP-IDF 版本过低或依赖未正确解析 | 使用 ESP-IDF v5.5 或更高版本 |
| 没有串口输出 | 串口选择错误或 Monitor 未启动 | 检查设备管理器或 idf.py -p PORT monitor |
02_lvgl_demo_v9
【功能说明】
该示例用于验证 AMOLED 显示屏、LVGL v9 图形库和 BSP 显示初始化流程。程序启动后会初始化显示，并运行 LVGL 官方 Demo。
当前入口代码默认运行：
lv_demo_benchmark();
代码中还预留了其他 LVGL Demo：
// lv_demo_music();
// lv_demo_widgets();
可以根据需要切换不同 Demo。
【代码入口】
主要入口文件：
02_lvgl_demo_v9/main/main.c
建议优先查看：
| 函数或接口 | 作用 |
|---|---|
app_main() | 应用入口 |
bsp_display_start() | 初始化显示、LVGL 和相关 BSP 资源 |
bsp_display_lock() | 进入 LVGL 临界区 |
lv_demo_benchmark() | 运行 LVGL 性能测试 Demo |
bsp_display_unlock() | 退出 LVGL 临界区 |
【正常运行现象】
屏幕点亮，并显示 LVGL Benchmark 测试界面。界面会持续刷新，用于测试图形绘制性能。
【修改示例】
如果要改为控件演示，可修改 main/main.c：
// lv_demo_benchmark();
lv_demo_widgets();
如果要改为音乐风格演示，可修改为：
// lv_demo_benchmark();
lv_demo_music();
修改后重新编译烧录：
idf.py -p PORT flash monitor
【常见排查】
| 现象 | 可能原因 | 建议处理 |
|---|---|---|
| 屏幕不亮 | 显示初始化失败、背光未打开、供电异常 | 先运行 01_AXP2101，确认 PMU 正常 |
| 屏幕有画面但颜色异常 | 显示格式或屏幕驱动配置异常 | 检查 BSP 组件和 sdkconfig.defaults |
| 编译时下载 LVGL 失败 | 网络无法访问组件仓库 | 检查网络代理，或提前下载依赖 |
| 触摸无反应 | 当前 Demo 不一定明显体现触摸功能 | 切换到 lv_demo_widgets() 或运行 03_esp-brookesia |
03_esp-brookesia
【功能说明】
该示例基于 Espressif 的 ESP-Brookesia 框架，展示一个类似手机系统的图形界面。它比基础 LVGL Demo 更接近实际产品 UI，适合屏幕、触摸、UI 动画和复杂界面组织方式。
主要作用：
- 初始化 BSP 显示。
- 打开显示背光。
- 注册 LVGL GUI 锁。
- 创建
Phone对象。 - 初始化并安装应用注册表中的 App。
- 创建定时器更新状态栏时间。
【代码入口】
主要入口文件：
03_esp-brookesia/main/main.cpp
建议优先查看：
| 函数或对象 | 作用 |
|---|---|
app_main() | 应用入口 |
bsp_display_start() | 初始化显示 |
bsp_display_backlight_on() | 打开背光 |
LvLock::registerCallbacks() | 注册 LVGL 线程安全锁 |
Phone | ESP-Brookesia 的手机 UI 系统对象 |
phone->begin() | 启动手机 UI 系统 |
phone->initAppFromRegistry() | 从注册表初始化 App |
phone->installAppFromRegistry() | 安装 App |
【正常运行现象】
屏幕显示手机风格 UI，可看到状态栏和应用界面。客户可以通过触摸进行页面或应用交互。
【常见排查】
| 现象 | 可能原因 | 建议处理 |
|---|---|---|
| 编译时间较长 | 该示例组件和资源文件较多 | 首次编译等待时间会更长，属于正常现象 |
| 编译失败并提示内存或分区问题 | 分区表或 PSRAM 配置不匹配 | 确认使用示例自带 sdkconfig.defaults 和 partitions.csv |
| 屏幕亮但 UI 不显示 | GUI 初始化失败或 LVGL 锁使用异常 | 查看串口中 Start display failed、Begin failed 等日志 |
| 触摸无反应 | 触摸初始化异常或 UI 未进入可交互页面 | 先运行 02_lvgl_demo_v9 验证基础显示，再检查 BSP 触摸配置 |
04_Immersive_block
【功能说明】
该示例使用 QMI8658 IMU 读取加速度数据，并通过 LVGL 在屏幕上绘制多个彩色图形。客户倾斜开发板时，屏幕中的图形会根据加速度方向移动，并进行边界限制和碰撞处理。
主要作用：
- 初始化 NVS。
- 初始化显示和背光。
- 初始化 QMI8658 IMU。
- 配置加速度计量程和输出速率。
- 执行水平校准。
- 创建图形更新任务。
- 使用 BOOT 按键触发重新校准。
【代码入口】
主要入口文件：
04_Immersive_block/main/main.c
建议优先查看：
| 函数 | 作用 |
|---|---|
app_main() | 初始化显示、IMU、按键和任务 |
perform_level_calibration() | 水平校准，采集 200 个加速度样本 |
shapes_update_task() | 周期性读取 IMU 数据并更新图形位置 |
generate_random_shapes() | 生成随机图形 |
apply_calibration_and_deadzone() | 应用校准偏移和死区过滤 |
init_calibration_button() | 配置 BOOT 按键中断 |
【正常运行现象】
屏幕显示多个彩色图形。将开发板水平放置时，程序会先进行校准。倾斜开发板后，图形会跟随倾斜方向移动。按下 BOOT 按键后，程序会重新进行水平校准。
【使用注意】
- 上电或复位后，请先将开发板放在稳定的水平面上，等待校准完成。
- 如果校准期间开发板晃动，程序会判断数据不稳定并自动重试。
- 如果图形在水平状态下仍明显移动，可按 BOOT 重新校准。
【常见排查】
| 现象 | 可能原因 | 建议处理 |
|---|---|---|
| 图形一直漂移 | 校准时开发板没有放平或桌面晃动 | 放平开发板后按 BOOT 重新校准 |
| 串口提示 IMU 初始化失败 | QMI8658 I2C 通信异常 | 检查 BSP I2C 初始化和 QMI8658 地址 |
| 屏幕没有图形 | 显示初始化失败或 LVGL 未刷新 | 先运行 02_lvgl_demo_v9 验证显示 |
| 按 BOOT 无反应 | 按键中断未注册或 GPIO 配置异常 | 检查 GPIO0 是否被其他功能占用 |
05_Spec_Analyzer
【功能说明】
该示例实现实时音频频谱分析。程序通过音频输入采集数据，使用 ESP-DSP 进行 FFT 计算，并在 AMOLED 屏幕上显示 64 条彩色对称频谱条和峰值指示。
主要作用：
- 初始化显示和背光。
- 初始化音频 Codec 和 I2S。
- 读取双声道音频数据。
- 将左右声道转换为单声道浮点采样。
- 对采样数据加 Hann 窗。
- 执行 FFT。
- 将频域数据映射为 64 条频谱显示。
- 使用 LVGL Canvas 绘制频谱。
【代码入口】
主要入口文件：
05_Spec_Analyzer/main/main.c
建议优先查看：
| 函数 | 作用 |
|---|---|
app_main() | 初始化显示、创建 Canvas、启动音频 FFT 任务 |
audio_fft_task() | 采集音频、执行 FFT、更新频谱数据 |
lv_example_canvas_10() | 创建 LVGL Canvas 和刷新定时器 |
timer_cb() | 根据频谱数据绘制彩色频谱条 |
关键参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
N_SAMPLES | 1024 | FFT 采样点数 |
SAMPLE_RATE | 16000 | 采样率 |
CHANNELS | 2 | 双声道输入 |
STRIPE_COUNT | 64 | 显示频谱条数量 |
CANVAS_WIDTH | 300 | 频谱画布宽度 |
CANVAS_HEIGHT | 150 | 频谱画布高度 |
【正常运行现象】
屏幕中央显示彩色频谱。环境声音变化时，频谱条高度会随声音强弱和频率分布变化。若对麦克风或音频输入源发声，频谱应有明显变化。
【常见排查】
| 现象 | 可能原因 | 建议处理 |
|---|---|---|
| 频谱没有变化 | 音频输入无信号、Codec 初始化失败 | 查看串口是否有 Audio codec init failed |
编译失败并提示 esp-dsp | 组件依赖未下载成功 | 检查网络或组件管理器 |
| 串口提示 I2S read error | I2S 或 Codec 配置异常 | 检查 components/bsp_extra 中音频初始化配置 |