ESP-IDF 开发

产品概述

ESP32-S3-Touch-LCD-7C 板载 7 英寸电容触控屏、音频模块与常用外设，可用于图形界面显示、语音交互和人机界面相关应用开发。

信息

对于 ESP32-S3-Touch-LCD-7C 开发板，示例默认使用 ESP-IDF V5.5.3，如其他版本编译失败，可回退至此版本测试。

快速上手

本章节包含以下内容：

ESP-IDF 入门教程
配置开发环境（Windows）
常用示例说明（简要概览与代码说明）

ESP-IDF 入门教程

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

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

配置开发环境

备注

以下内容以 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 环境,无需手动配置。

注意

若安装失败或需重装，可尝试删除 C:\Users\%Username%\esp 与 C:\Users\%Username%\.espressif 后重试。

烧录程序

在安装完 ESP-IDF 的开发环境之后，选择文件夹打开示例
在弹出的窗口当中选择示例包解压后的 ESP-IDF 目录下的示例，点击选择文件（这里用 01_GPIO 文件夹作为示例）。
为了将对应的代码上传到 ESP32-S3，需要用 Type-C 转 Type-A 的线将 ESP32-S3-Touch-LCD-7C 的 USB TO UART Type-C 接口接到电脑的 USB 口。
若是新工程首次烧录程序，需要先选择识别出来的 COM 口，例如此处识别到的是 COM36。
选择下载方式为：UART。
接着选择主芯片为 ESP32S3。

选择 openocd 的路径，此处无影响，选择第一个即可。
点击下方 Build Flash Monitor 一键按钮，用于连续执行 Build --> Flash --> Monitor。
开发板板载自动下载电路，无需手动操作即可自动下载。等待编译烧录完成即可，首次编译可能需要较长时间。

示例程序

下面给出每个示例的目的、要点说明与运行效果（以便快速上手）。

示例程序	基础例程说明
01_I2C	测试 I2C 接口通信
02_RTC	测试 RTC 实时时钟功能
03_LCD	测试 LCD 显示功能
04_ISOLATION_IO	测试隔离 IO 功能
05_BAT_INFO	测试电池信息读取
06_SD	测试 SD 卡读写功能
07_TOUCH	测试触摸屏功能
08_DISPLAY_BMP	显示 BMP 图片
09_SPEAKER_MICROPHONE	测试扬声器与麦克风
10_LVGL_CODEC	LVGL 编解码器示例

01_I2C

硬件连接

使用 USB 线将开发板接入电脑

代码分析

背光控制代码

    while (1)
    {
        // Set the IO_EXTENSION_IO_2 pin to high (turn on the backlight)
        IO_EXTENSION_Output(IO_EXTENSION_IO_2, 1);  // Turn on backlight
        vTaskDelay(500 / portTICK_PERIOD_MS);  // Wait for 500 milliseconds

        // Set the IO_EXTENSION_IO_2 pin to low (turn off the backlight)
        IO_EXTENSION_Output(IO_EXTENSION_IO_2, 0);  // Turn off backlight
        vTaskDelay(500 / portTICK_PERIOD_MS);  // Wait for 500 milliseconds
    }

代码解释

while (1)：持续循环执行背光开关测试逻辑。
IO_EXTENSION_Output(IO_EXTENSION_IO_2, 1)：将 IO 扩展芯片的 IO_2 输出为高电平，用于打开 LCD 背光。
IO_EXTENSION_Output(IO_EXTENSION_IO_2, 0)：将 IO_2 输出为低电平，用于关闭 LCD 背光。
vTaskDelay(500 / portTICK_PERIOD_MS)：延时约 500 ms，控制背光开关的闪烁节奏。

运行效果

可看到 LCD 背光闪烁效果。

02_RTC

硬件连接

使用 USB 线将开发板接入电脑

代码分析

RTC 初始化代码

    // Initialize the I2C interface
    DEV_I2C_Init();

    // Initialize external IO extension chip
    IO_EXTENSION_Init();

    // Initialize PCF85063A RTC
    PCF85063A_Init();

    // Set current time
    PCF85063A_Set_All(Set_Time);

    // Set alarm time
    PCF85063A_Set_Alarm(Set_Alarm_Time);

    // Enable alarm interrupt
    PCF85063A_Enable_Alarm();

代码解释

DEV_I2C_Init()：初始化 I2C 总线，为后续 RTC 与 IO 扩展芯片通信做准备。
IO_EXTENSION_Init()：初始化外部 IO 扩展芯片（用于 RTC 中断等外设信号读写）。
PCF85063A_Init()：初始化 PCF85063A RTC 芯片。
PCF85063A_Set_All(Set_Time)：设置 RTC 当前时间。
PCF85063A_Set_Alarm(Set_Alarm_Time)：设置 RTC 闹钟时间。
PCF85063A_Enable_Alarm()：使能闹钟中断，便于触发闹钟提示。

运行效果

串口打印 RTC 时间。

03_LCD

硬件连接

使用 USB 线将开发板接入电脑

代码分析

app_main()：
- 初始化 LCD 显示屏
- 测试 LCD 显示功能
- 显示文本、图形和图片

运行效果

烧录成功后，屏幕显示测试内容。
可看到文本、图形和图片显示效果。

04_ISOLATION_IO

硬件连接

使用 USB 线将开发板接入电脑

代码分析

app_main()：
- 初始化隔离 IO
- 测试隔离 IO 输入输出功能

运行效果

烧录成功后，若 IO 均成功互联，屏幕显示绿色，否则显示红色。

05_BAT_INFO

硬件连接

使用 USB 线将开发板接入电脑
连接锂电池到开发板

代码分析

电池信息显示代码

    if (bat_info.ma > 0) {
      sprintf(bat,
              "%d%% | %dmV | %dmA | %dC | TTF=%d min | Rem=%dmAh | FCC=%dmAh | "
              "Cyc=%d | SOH=%d%%",
              bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc, bat_info.ttf,
              bat_info.mah_rem, bat_info.mah_fcc, bat_info.cycles,
              bat_info.soh);

      Paint_DrawString_EN(50, 130, bat, &Font48, GREEN, WHITE);

      waveshare_rgb_lcd_display(BlackImage);
      // 正在充电：显示 TTF（充满剩余时间）
      ESP_LOGI("BQ27220",
               "%d%% | %dmV | %dmA | %dC | TTF=%d min | Rem=%dmAh | FCC=%dmAh "
               "| Cyc=%d | SOH=%d%%",
               bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc,
               bat_info.ttf, bat_info.mah_rem, bat_info.mah_fcc,
               bat_info.cycles, bat_info.soh);
    } else {
      sprintf(bat,
              "%d%% | %dmV | %dmA | %dC | TTE=%d min | Rem=%dmAh | FCC=%dmAh | "
              "Cyc=%d | SOH=%d%%",
              bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc, bat_info.tte,
              bat_info.mah_rem, bat_info.mah_fcc, bat_info.cycles,
              bat_info.soh);

      Paint_DrawString_EN(50, 130, bat, &Font48, RED, WHITE);

      waveshare_rgb_lcd_display(BlackImage);

      // 正在放电：显示 TTE（还能用多久）
      ESP_LOGI("BQ27220",
               "%d%% | %dmV | %dmA | %dC | TTE=%d min | Rem=%dmAh | FCC=%dmAh "
               "| Cyc=%d | SOH=%d%%",
               bat_info.soc, bat_info.mv, bat_info.ma, bat_info.tc,
               bat_info.tte, bat_info.mah_rem, bat_info.mah_fcc,
               bat_info.cycles, bat_info.soh);
    }

代码解释

bat_info.ma > 0：按当前逻辑，将电流为正视为充电状态；否则视为放电状态。
sprintf(bat, "...", ...)：将电量、电压、电流、温度、剩余时间等字段格式化成字符串，便于屏幕显示。
Paint_DrawString_EN(...)：将电池信息绘制到 LCD；充电用 GREEN，放电用 RED 区分状态。
waveshare_rgb_lcd_display(BlackImage)：刷新屏幕，将绘制内容显示出来。
ESP_LOGI("BQ27220", "...", ...)：在串口日志中输出同样的电池信息，便于调试与对照。

运行效果

烧录成功后，屏幕显示电池信息。

06_SD

硬件连接

使用 USB 线将开发板接入电脑
插入 Micro SD 卡到开发板

代码分析

app_main()：
- 初始化 SD 卡
- 测试 SD 卡读写功能

运行效果

烧录成功后，屏幕显示 SD 卡信息和测试结果。

07_TOUCH

硬件连接

使用 USB 线将开发板接入电脑
app_main()：
- 初始化显示屏和触摸屏驱动
- 读取触摸屏数据并显示

运行效果

烧录成功后，可正常触摸触摸屏，屏幕显示对应触控 UI 元素。

08_DISPLAY_BMP

硬件连接

使用 USB 线将开发板接入电脑
插入包含 BMP 图片的 Micro SD 卡

代码分析

app_main()：
- 初始化 SD 卡和 LCD
- 读取并显示 BMP 图片

运行效果

烧录成功后，屏幕显示 BMP 图片。

09_SPEAKER_MICROPHONE

硬件连接

使用 USB 线将开发板接入电脑
连接扬声器和麦克风

代码分析

音频触摸控制代码

        point_data = touch_gt911_read_point(1);
        if (point_data.cnt == 1)
        {
            if (!(prev_x == point_data.x[0] && prev_y == point_data.y[0]))
            {
                if (point_data.x[0] > 390 && point_data.x[0] < 420 &&
                    point_data.y[0] > 420 && point_data.y[0] < 480)
                {
                    Paint_Clear(WHITE);
                    is_playing = true;
                    play_or_pause(is_playing);
                    is_playing = false;
                    play_or_pause(is_playing);

                    Paint_Clear(WHITE);
                    Paint_DrawCircle(405, 450, 15, RED, DOT_PIXEL_2X2, DRAW_FILL_FULL);
                    Paint_DrawString_EN(100, 150, "Click to record/play", &Font48, BLACK, WHITE);
                    waveshare_rgb_lcd_display(BlackImage);

                    prev_x = point_data.x[0];
                    prev_y = point_data.y[0];
                }
            }
        }

代码解释

touch_gt911_read_point(1)：读取 GT911 触摸控制器的触摸点数据（此处取 1 组数据）。
point_data.cnt == 1：仅在单点触摸时进入处理逻辑，避免多点触摸干扰。
prev_x / prev_y：记录上一次触摸坐标，用于过滤重复触发。
坐标范围判断：当触摸点落在 (x: 390~420, y: 420~480) 的区域内，视为点击了界面上的控制区域。
play_or_pause(...)：按当前状态执行播放/暂停控制（示例中依次调用两次，用于演示控制流程）。
Paint_DrawCircle(...) / Paint_DrawString_EN(...)：绘制按钮与提示文本，并通过 waveshare_rgb_lcd_display(...) 刷新显示。

运行效果

烧录成功后，可通过麦克风录音并通过扬声器播放录音。

10_LVGL_CODEC

硬件连接

使用 USB 线将开发板接入电脑

代码分析

LVGL 编解码器初始化代码

    speaker_codec_init();
    speaker_codec_volume_set(50, NULL);
    speaker_player_register_callback(speaker_callback, NULL);
    speaker_player_init();

    // Lock the mutex due to the LVGL APIs are not thread-safe
    if (lvgl_port_lock(-1)) {
        user_lv_demo_music();
        // Release the mutex
        lvgl_port_unlock();
    }
    IO_EXTENSION_Pwm_Output(100); // Set backlight brightness to maximum
    waveshare_rgb_lcd_bl_on(); // Turn on the LCD backlight

代码解释

speaker_codec_init()：初始化音频编解码器硬件。
speaker_codec_volume_set(50, NULL)：设置音量为 50（具体范围以实现为准）。
speaker_player_register_callback(...)：注册播放回调函数，用于接收播放状态事件。
speaker_player_init()：初始化播放器模块。
lvgl_port_lock(-1) / lvgl_port_unlock()：LVGL API 非线程安全，调用 UI 前先加锁，完成后解锁。
user_lv_demo_music()：启动示例 LVGL 音乐界面。
IO_EXTENSION_Pwm_Output(100)：通过 IO 扩展输出 PWM，将背光亮度设置为最大。
waveshare_rgb_lcd_bl_on()：打开 LCD 背光输出。

运行效果

烧录成功后，屏幕显示 LVGL 界面，并且可以正常播放音乐（需要提前插入 SD 卡）。

文档反馈

产品概述​

快速上手​

ESP-IDF 入门教程​

配置开发环境​

安装 ESP-IDF 开发环境​

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

烧录程序​

示例程序​

01_I2C​

硬件连接​

代码分析​

代码解释​

运行效果​

02_RTC​

硬件连接​

代码分析​

代码解释​

运行效果​

03_LCD​

硬件连接​

代码分析​

运行效果​

04_ISOLATION_IO​

硬件连接​

代码分析​

运行效果​

05_BAT_INFO​

硬件连接​

代码分析​

代码解释​

运行效果​

06_SD​

硬件连接​

代码分析​

运行效果​

07_TOUCH​

硬件连接​

运行效果​

08_DISPLAY_BMP​

硬件连接​

代码分析​

运行效果​

09_SPEAKER_MICROPHONE​

硬件连接​

代码分析​

代码解释​

运行效果​

10_LVGL_CODEC​

硬件连接​

代码分析​

代码解释​

运行效果​

产品概述

快速上手

ESP-IDF 入门教程

配置开发环境

安装 ESP-IDF 开发环境

安装 Visual Studio Code 与 ESP-IDF 扩展

烧录程序

示例程序

01_I2C

硬件连接

代码分析

代码解释

运行效果

02_RTC

硬件连接

代码分析

代码解释

运行效果

03_LCD

硬件连接

代码分析

运行效果

04_ISOLATION_IO

硬件连接

代码分析

运行效果

05_BAT_INFO

硬件连接

代码分析

代码解释

运行效果

06_SD

硬件连接

代码分析

运行效果

07_TOUCH

硬件连接

运行效果

08_DISPLAY_BMP

硬件连接

代码分析

运行效果

09_SPEAKER_MICROPHONE

硬件连接

代码分析

代码解释

运行效果

10_LVGL_CODEC

硬件连接

代码分析

代码解释

运行效果