跳到主要内容

ESP-IDF 开发

本章节包含以下内容：

ESP-IDF 入门教程​

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

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

配置开发环境​

备注

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

安装 ESP-IDF 开发环境​

  1. 前往 ESP-IDF Installation Manager 下载 ESP-IDF 安装管理器。这是乐鑫最新推出的跨平台安装工具，下文将演示如何使用其离线安装功能。

    在页面中点击 Offline Installer 标签，然后在筛选栏中选择 Windows 操作系统和你要安装的版本。

    下载 EIM 和整合包

    确认选择无误后，点击下载按钮。浏览器将自动同时下载两个文件：一个是 ESP-IDF 离线整合包(.zst)，另一个是 ESP-IDF 安装器(.exe)。

    下载 EIM 和整合包2

    请耐心等待两个文件下载完成。

  2. 下载完成后，双击运行 ESP-IDF 安装器(eim-gui-windows-x64.exe)。

    启动后，可在右上角将界面语言切换为中文。

    切换 EIM 语言

    安装工具会自动检测同一目录下是否存在离线整合包。点击 从存档安装。

    自动检测整合包

    接下来，选择安装路径。建议使用默认路径；若需自定义，请确保路径中不包含中文或空格。确认无误后，点击 开始安装。

    选择安装路径

  3. 当看到如下界面时，表示 ESP-IDF 已安装成功。

    安装成功

  4. 建议同时安装驱动程序。点击 完成安装，然后点击 安装驱动程序。

    用 ESP-IDF 安装管理器安装驱动

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

  1. 下载并安装 Visual Studio Code。

  2. 安装时建议勾选 通过 Code 打开操作添加到 Windows 资源管理器文件上下文菜单,以便快速打开项目文件夹。

  3. 在 VS Code 中,点击侧边活动栏中的 扩展图标 扩展图标(或使用快捷键 Ctrl + Shift + X)打开 扩展 视图。

  4. 在搜索框中输入 ESP-IDF,找到 ESP-IDF 扩展并点击安装。

    在 VS Code 中搜索并安装 ESP-IDF 扩展

  5. 当 ESP-IDF 扩展版本 ≥ 2.0 时,扩展会自动检测并识别上述步骤中安装的 ESP-IDF 环境,无需手动配置。

注意

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

烧录程序​

  1. 在安装完 ESP-IDF 的开发环境之后，选择文件夹打开示例

    在 VS Code 中打开文件夹

  2. 在弹出的窗口当中选择示例包解压后的 ESP-IDF 目录下的示例，点击选择文件（这里用 01_GPIO 文件夹作为示例）。

    在 VS Code 中打开文件

  3. 为了将对应的代码上传到 ESP32-S3，需要用 Type-C 转 Type-A 的线将 ESP32-S3-Touch-LCD-7B 的 USB TO UART Type-C 接口接到电脑的 USB 口。

  4. 若是新工程首次烧录程序，需要先选择识别出来的 COM 口，例如我这边识别到的是 COM36。

    选择 COM 口

  5. 选择下载方式为：UART。

    选择下载方式

  6. 接着选择主芯片为 ESP32S3。

    选择主芯片

    选择 openocd 的路径，这里对我们没有影响，所以我们随便选择一个即可，此处可选择第一个。

    选择 openocd 的路径

  7. 点击下列的小火苗 Build Flash Monitor 一键按钮，用于连续执行 Build-->Flash-->Monitor。

    选择小火苗

  8. 板子上板载自动下载电路，无需手动操作即可自动下载。接着等待编译烧录完成就好，首次编译可能需要较长时间才能完成。

    编译下载完成

示例程序​

示例程序位于示例包的 ESP-IDF 目录： https://files.waveshare.net/wiki/ESP32-S3-Touch-LCD-7B/ESP32-S3-Touch-LCD-7B-BOX-Demo.zip

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

示例程序基础例程说明
01_GPIO测试 GPIO 输出控制 LED
02_UART测试 UART 串口回环
03_I2C测试 I2C 与 IO 扩展控制背光
04_CAN测试 CAN 接口收发及告警
05_RS485测试 RS485 数据回环
06_LCD测试 RGB LCD 显示与旋转
07_SD测试 SD 卡挂载与容量读取
08_TOUCH测试电容触摸屏多点触控
09_DISPLAY_BMP从 SD 卡读取并切换 BMP 图片
10_WIFI_SCAN扫描附近 WiFi 并显示列表
11_WIFI_STA作为 STA 连接指定 WiFi 并显示 IP
12_WIFI_AP建立 AP 热点并显示连接设备
13_LVGL_TRANSPLANT运行 LVGL 官方 widgets Demo
14_LVGL_BTN使用 LVGL 按钮控制 LED 亮灭
15_LVGL_SLIDER使用滑动条调节亮度并显示电压
16_LVGL_UI运行综合 GUI，集成多种外设测试

01_GPIO​

硬件连接​

  • 使用 USB 线将开发板接入电脑
  • 将 LED 模块连接到指定 GPIO 引脚（示例使用 GPIO6）

代码分析​

  • app_main()：
    • 初始化 GPIO6，配置为输出模式
    • 在循环中交替输出高低电平，控制 LED 亮灭，实现约 1 Hz 的闪烁效果

运行效果​

  • 烧录成功后，屏幕无显示

  • 连接的 LED 灯以约 1 Hz 频率亮灭

    ESP32-S3-Touch-LCD-7B-IDF-example-01

02_UART​

硬件连接​

  • 使用 USB 线连接板子的 UART 口，接入电脑

    ESP32-S3-Touch-LCD-7B-IDF-example-02

代码分析​

  • app_main()：
    • 初始化串口外设，设置波特率、数据位、校验位、停止位等参数
    • 分配临时缓冲区，用于接收串口数据
    • 在循环中轮询串口接收，如果有数据则读出并立即发送回去，实现简单的“串口回环”功能

运行效果​

  • 烧录成功后，打开串口调试助手，向 ESP32-S3-Touch-LCD-7B 发送任意数据
  • 开发板会原样回传收到的数据到串口调试助手

03_I2C​

硬件连接​

  • 使用 USB 线将开发板接入电脑
  • 如需外接 I2C 设备，可通过板载 I2C 座子连接

代码分析​

  • app_main()：
    • 调用 DEV_I2C_Init() 初始化 I2C 总线
    • 调用 IO_EXTENSION_Init() 初始化 IO 扩展芯片
    • 在循环中通过 IO 扩展控制背光引脚，使屏幕背光周期性亮灭
  • DEV_I2C_Init()：完成 I2C 外设的基本初始化
  • IO_EXTENSION_Init()：初始化 IO 扩展芯片
  • IO_EXTENSION_Output(uint8_t pin, uint8_t value)：控制指定扩展引脚输出高/低电平

运行效果​

  • 烧录成功后，屏幕背光会以约 1 Hz 的频率亮灭

04_CAN​

硬件连接​

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

  • 使用 USB-CAN-A 工具板将其与开发板 CAN 接口连接

    ESP32-S3-Touch-LCD-7B-IDF-example-04

代码分析​

  • app_main()：
    • 初始化 I2C、IO 扩展以及 CAN 接口
    • 在初始化 CAN 前，将 IO_EXTENSION_IO_5 拉高以使 CAN 接口工作
    • 调用 can_init(twai_timing_config_t, twai_filter_config_t, twai_general_config_t) 完成 TWAI 初始化
    • 在循环中通过 can_read_alerts() 读取告警并获取状态，根据不同告警类型打印日志，例如错误被动、总线错误、传输失败、传输成功等
    • 当接收到有效数据帧时，将其原样回发，实现 CAN 回环测试

运行效果​

  • 烧录成功后，屏幕无显示

  • 在 USB-CAN-A_TOOL 中向 ESP32-S3-Touch-LCD-7B 发送 CAN 消息，可看到设备返回相同的消息

    ESP32-S3-Touch-LCD-7B-IDF-example-04-01

    ESP32-S3-Touch-LCD-7B-IDF-example-04-02

05_RS485​

硬件连接​

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

  • 使用 USB 转 RS485 转换器连接开发板 RS485 接口

    ESP32-S3-Touch-LCD-7B-IDF-example-05

代码分析​

  • app_main()：
    • 调用 DEV_UART_Init() 初始化串口，设置波特率、引脚等参数
    • 分配接收缓冲区，用于缓存 RS485 收到的数据
    • 在循环中检查是否有数据可读，如有则读出并立即发送回去，实现 RS485 数据回环

运行效果​

  • 烧录成功后，打开串口调试助手（RS485 模式）向 ESP32-S3-Touch-LCD-7B 发送数据

  • 开发板会原样回传收到的数据

    ESP32-S3-Touch-LCD-7B-IDF-example-05-01

06_LCD​

硬件连接​

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

代码分析​

  • app_main()：
    • 初始化 I2C、IO 扩展和 RGB LCD，并打开背光
    • 创建帧缓存，用于存放要显示的图像数据
    • 初始化 GUI 图像数据，设置图像格式和旋转角度（可在示例中修改角度）
    • 依次在屏幕上显示颜色条、图案、文本和图片，用于验证 LCD 显示
  • waveshare_esp32_s3_rgb_lcd_init()：完成 RGB LCD 初始化
  • waveshare_rgb_lcd_bl_on()：打开 LCD 背光

运行效果​

  • 烧录成功后，先显示 RGB565 颜色条

  • 随后显示图案和文本，最后显示图片

07_SD​

硬件连接​

  • 使用 USB 线将开发板接入电脑
  • 将 Micro SD 卡插入 ESP32-S3-Touch-LCD-7B 的 SD 卡座

代码分析​

  • app_main()：
    • 初始化 SD 卡并挂载文件系统
    • 调用相关函数读取 SD 卡容量与可用空间，并在屏幕上显示
  • sd_mmc_init()：初始化 SD/MMC 接口并挂载文件系统
  • read_sd_capacity(uint64_t *total_capacity, uint64_t *available_capacity)：读取 SD 卡总容量和可用容量

运行效果​

  • 烧录成功后，屏幕显示 SD 卡容量等信息

  • 若挂载失败或无卡，将显示 "SD Card Fail!"

08_TOUCH​

硬件连接​

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

代码分析​

  • app_main()：
    • 完成电容触摸屏及显示初始化
    • 在循环中读取触摸点，并在屏幕上绘制触点
  • touch_gt911_init()：初始化 GT911 触摸控制器
  • touch_gt911_read_point(uint8_t max_touch_cnt)：读取当前触摸点，最多识别 5 点

运行效果​

  • 烧录成功后，触摸屏幕会在相应位置显示触摸点

  • 同时触摸多点，最多可显示 5 个不同颜色的点

09_DISPLAY_BMP​

硬件连接​

  • 使用 USB 线将开发板接入电脑
  • 将示例目录下的 BMP 图片拷贝到 Micro SD 卡，再插入开发板

代码分析​

  • app_main()：
    • 初始化 SD 卡与 LCD 后，读取 SD 卡中的 BMP 图像文件
    • 在屏幕上显示左右箭头，通过触摸箭头切换图片
  • list_files(const char *base_path)：
    • 遍历指定路径，读取 BMP 文件名并保存到数组中
  • GUI_ReadBmp(UWORD Xstart, UWORD Ystart, const char *path)：
    • 从 SD 卡读取 BMP 图像数据写入帧缓冲，其中 Xstart、Ystart 决定显示位置

运行效果​

  • 烧录成功并成功挂载 SD 卡后，屏幕显示箭头图标

  • 点击箭头，即可依次浏览 SD 卡中的图片，并进行左右切换

10_WIFI_SCAN​

硬件连接​

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

代码分析​

  • app_main()：
    • 初始化 WiFi 子系统，配置为 STA 模式
    • 调用扫描函数搜索附近 2.4 GHz WiFi，并将结果写入缓冲区
  • wifi_scan()：负责执行实际 WiFi 扫描并保存结果

运行效果​

  • 烧录成功后，开发板开始扫描附近 WiFi

  • 扫描结束后，屏幕显示扫描到的 WiFi 名称列表（暂不支持中文 SSID 显示）

11_WIFI_STA​

硬件连接​

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

代码分析​

  • app_main()：
    • 初始化 WiFi 为 STA 模式
    • 使用预设的 SSID/密码连接指定 2.4 GHz WiFi
    • 连接成功后，在屏幕上显示获取到的 IP 地址

运行效果​

  • 烧录成功后，开发板连接到配置好的 WiFi

  • 连接成功后，屏幕上显示当前 IP 地址

12_WIFI_AP​

硬件连接​

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

代码分析​

  • app_main()：
    • 将 WiFi 配置为 AP 模式
    • 创建名为 "ESP32-S3-Touch-LCD-7B" 的热点
    • 实时统计并显示当前连接到该热点的设备 MAC 地址

运行效果​

  • 烧录成功后，开发板作为热点工作

  • 屏幕上显示连接设备的 MAC 地址列表

13_LVGL_TRANSPLANT​

硬件连接​

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

代码分析​

  • app_main()：
    • 完成 LCD、触摸及 LVGL 相关初始化
    • 运行 LVGL 的 lv_demo_widgets 演示界面，展示常见控件

运行效果​

  • 烧录成功后，屏幕进入 lv_demo_widgets 界面，可通过触摸进行交互

其他说明​

  • 示例使用 LVGL 8.4 版本，可参考官方文档查询 API
  • 若出现屏幕“漂移”等问题，可参考乐鑫官方 FAQ
  • 自己的 UI 程序如提示内存不足，可在工具菜单中选择更大的分区表

14_LVGL_BTN​

硬件连接​

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

  • 将 LED 模块连接到指定 GPIO 引脚

    ESP32-S3-Touch-LCD-7B-IDF-example-14-01

代码分析​

  • app_main()：
    • 初始化硬件与 LVGL
    • 创建一个按钮控件，在按钮回调中切换某个 GPIO 电平，从而控制 LED 亮灭

运行效果​

  • 烧录成功后，屏幕上显示一个按钮

  • 点击按钮时，对应 GPIO 状态翻转，外接 LED 随之亮灭

15_LVGL_SLIDER​

硬件连接​

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

  • 将 LED 模块连接到指定 GPIO 引脚

    ESP32-S3-Touch-LCD-7B-IDF-example-15-01

代码分析​

  • app_main()：
    • 初始化硬件与 LVGL
    • 创建滑动条控件和文本显示区域，用于显示电池电压
    • 根据滑动条当前位置调节 LED 和屏幕背光亮度，并实时更新电池电压显示

运行效果​

  • 烧录成功后，屏幕显示滑动条与当前电池电压
  • 拖动滑动条时，LED 与屏幕亮度同步变化

16_LVGL_UI​

硬件连接​

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

代码分析​

  • app_main()：
    • 初始化硬件与 LVGL
    • 加载由 SquareLine Studio 设计的自定义 GUI 界面（通过导出 C 代码集成）
    • 首次运行时提示创建登录名和密码
    • 登录成功后进入主界面，包含多个功能入口：WIFI、RS485、CAN、PWM 等
    • 各页面可分别测试对应外设的收发、速率设置或背光、SD 卡、电池电压读取等功能

运行效果​

  • 第一次运行需要创建登录名和密码，随后返回登录界面

  • 输入账户信息登录后，可在界面中切换 WIFI、RS485、CAN、PWM 等功能，并进行交互测试

最后由 CQ793 于 更新