ESP-IDF

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

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

ESP-IDF 入门教程

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

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

配置 ESP-IDF 开发环境

信息

对于 ESP32-S3-Touch-LCD-1.47 开发板，需要使用 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_Factory	综合测试程序	-
02_SD	测试 SD 卡读写	-
03_Brightness	lvgl 示例程序	-
04_LVGL	使用 lvgl 跑分示例	-

01_Factory

【程序说明】

本示例测试 ESP32-C3-LCD-1.47 板载模块的功能，屏幕上将显示各个模块的信息，用户可以通过按下BOOT按键进行页面切换

【硬件连接】

将板子接入电脑
将 Micro SD 卡插入卡槽

【代码分析】

IO_EXTENSION_Init()：初始化 IO 扩展（如背光/按键等外设控制口）。
LCD_Init()：初始化 LCD 屏与显示接口。
SD_Init() / QMI8658_Init() / Wireless_Init()：初始化 SD 卡、IMU、无线等板载模块，用于综合功能演示。
lvgl_display_init() / Lvgl_Example1()：初始化 LVGL 显示并启动示例 UI 页面。

while (true) { lv_timer_handler(); ... }：在任务循环里周期性驱动 LVGL 和传感器轮询，保持界面与数据刷新。

void Factory_Example(void)
{
    ESP_LOGI(TAG, "board init");
    IO_EXTENSION_Init();
    ESP_ERROR_CHECK(LCD_Init());
    SD_Init();
    QMI8658_Init();
    Wireless_Init();

    ESP_LOGI(TAG, "lvgl init");
    lvgl_display_init();
    Lvgl_Example1();

    while (true) {
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(10));
        QMI8658_Loop();
    }
}

【运行效果】

烧录完程序，屏幕上将显示图片。

02_SD

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 测试读取SD卡中的jpg图片并且显示在屏幕上。

【硬件连接】

将板子接入电脑
将 Micro SD 卡插入卡槽（SD 卡需要格式化为 FAT32 ）
将图片 image_01.jpg 放到 SD 卡的根目录下

【代码分析】

ESP_GOTO_ON_ERROR(..., EXIT, ...)：串行初始化/检查流程，任一步失败直接跳转到统一退出路径，减少层层判断。
jpg_decode_buffer_init()：初始化 JPEG 解码所需的全局缓冲区。
sd_init_with_retry() / sd_find_jpg() / sd_read_file_retry()：SD 卡初始化、查找 jpg、读取文件（带重试），提升可靠性。
lcd_draw_jpg(jpg_data, jpg_size)：对读到的 jpg 数据解码并绘制到屏幕。

EXIT: free(jpg_data)：释放动态申请的图片缓存，随后进入 while (true) 保持任务存活便于观察现象。

void SD_Example(void)
{
    esp_err_t ret = ESP_OK;
    char jpg_path[SD_EXAMPLE_PATH_MAX] = {0};
    uint8_t *jpg_data = NULL;
    size_t jpg_size = 0;

    ESP_GOTO_ON_ERROR(IO_EXTENSION_Init(), EXIT, TAG, "IO init failed");
    ESP_GOTO_ON_ERROR(LCD_Init(), EXIT, TAG, "LCD init failed");
    ESP_GOTO_ON_ERROR(jpg_decode_buffer_init(), EXIT, TAG, "alloc global jpg buffer failed");
    ESP_GOTO_ON_ERROR(sd_init_with_retry(), EXIT, TAG, "SD init failed");
    ESP_GOTO_ON_ERROR(sd_find_jpg(jpg_path, sizeof(jpg_path)), EXIT, TAG, "jpg not found");
    ESP_GOTO_ON_ERROR(sd_read_file_retry(jpg_path, &jpg_data, &jpg_size), EXIT, TAG, "read jpg failed");
    ESP_GOTO_ON_ERROR(lcd_draw_jpg(jpg_data, jpg_size), EXIT, TAG, "draw jpg failed");

EXIT:
    free(jpg_data);
    while (true) {
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
}

【运行效果】

烧录完程序，屏幕上将显示图片。

03_Brightness

【程序说明】

本示例演示了通过BOOT按键控制屏幕亮度,通过双击BOOT按键可以切换控制逻辑。

【硬件连接】

将板子接入电脑

【代码分析】

IO_EXTENSION_Init() / LCD_Init()：初始化 IO 扩展与 LCD 显示，为 LVGL 显示提供底层驱动。
lvgl_display_init()：注册显示驱动与缓冲区，让 LVGL 可以正常刷新屏幕。
boot_key_init() / boot_key_poll()：初始化并轮询 BOOT 按键，用于切换亮度调节逻辑/触发事件。
ui_init()：初始化亮度控制示例的界面元素（文本、进度条等）。

while (true) { ... lv_timer_handler(); ... }：循环驱动按键与 LVGL 任务调度，实现实时 UI 更新。

void Brightness_Example(void)
{
    ESP_ERROR_CHECK(IO_EXTENSION_Init());
    ESP_ERROR_CHECK(LCD_Init());
    lvgl_display_init();
    boot_key_init();
    ui_init();

    while (true) {
        boot_key_poll();
        lv_timer_handler();
        vTaskDelay(pdMS_TO_TICKS(10));
    }
}

【运行效果】

04_LVGL

【程序说明】

本示例演示了 ESP32-C3-LCD-1.47 运行 lvgl 跑分示例。

void LVGL_Benchmark_Example(void)
{
    ESP_ERROR_CHECK(IO_EXTENSION_Init());
    ESP_ERROR_CHECK(LCD_Init());
    lvgl_display_init();
    xTaskCreate(lvgl_benchmark_task, "lvgl_bench", 6144, NULL, 5, NULL);
}

【代码分析】

IO_EXTENSION_Init() / LCD_Init()：初始化板级 IO 与 LCD 显示接口。
lvgl_display_init()：初始化 LVGL 显示层，使 benchmark 可以输出到屏幕。
xTaskCreate(lvgl_benchmark_task, ...)：创建跑分任务，避免在初始化函数内阻塞；benchmark 逻辑在独立任务里执行并刷新界面。

【运行效果】

文档反馈

ESP-IDF 入门教程​

配置 ESP-IDF 开发环境​

安装 ESP-IDF 开发环境​

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

示例程序​

01_Factory​

02_SD​

03_Brightness​

04_LVGL​

ESP-IDF 入门教程

配置 ESP-IDF 开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

示例程序

01_Factory

02_SD

03_Brightness

04_LVGL