跳到主要内容

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

烧录程序​

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

    在 VS Code 中打开文件夹

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

    在 VS Code 中打开文件

  3. 为了将对应的代码上传到 ESP32-S3，需要用 Type-C 转 Type-A 的线将 ESP32-S3-Touch-LCD-4.3B 的 USB 口接到电脑的 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-4.3B/ESP32-S3-Touch-LCD-4.3B-BOX-Demo.zip

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

示例程序基础例程说明
01_I2C_Test测试I2C座子
02_RS485_Test测试RS485座子
03_SD_Test测试SD卡座
04_RTC_TestRTC时钟跟RTC中断
05_IO_Test测试隔离IO
06_TWAItransmit测试CAN卡座
07_TWAIreceive测试CAN卡座
08_lvgl_Porting移植LVGL

01_I2C_Test​

本示例演示如何通过 I2C 接口扫描总线上的设备，验证 I2C 座子及板载 I2C 器件的通信状态。

硬件连接​

  • 使用 USB 线把板子接入电脑
  • 可在 I2C 座子接入外部 I2C 设备（可选）

代码分析​

  • app_main()：示例入口，配置串口控制台和 I2C 主机总线。
  • esp_console_new_repl_*()：根据配置选择 UART / USB_CDC / USB_SERIAL_JTAG 作为命令行接口，创建 REPL 环境。
  • i2c_new_master_bus()：按照 SDA/SCL 引脚和时钟参数初始化 I2C 主机总线。
  • register_i2ctools()：注册 i2cdetect、i2cget、i2cset 等 I2C 工具命令，方便在串口中直接操作 I2C 设备。
  • esp_console_start_repl()：启动命令行循环，等待用户输入命令并执行。

运行效果​

  • 串口调试助手会每 5 秒打印一次扫描到的 I2C 设备地址。

    ESP32_IDF_01

02_RS485_Test​

本示例演示如何使用 ESP32-S3 的硬件串口进行 RS485 数据收发。

硬件连接​

  • 使用 USB 线把板子接入电脑

  • 将 RS485 座子的 A/B 端接入外部 RS485 设备

    ESP32_Arduino_RS485_Connect

代码分析​

  • app_main()：示例入口函数，创建 echo_task 任务并启动串口回环测试。
  • echo_task()：在循环中持续收发数据，实现 RS485 回环功能。
  • uart_driver_install()：安装 UART 驱动并分配接收缓冲区。
  • uart_param_config()：配置波特率、数据位、校验位等串口参数。
  • uart_set_pin()：绑定 TX/RX 引脚到对应的 RS485 接口引脚。
  • uart_read_bytes() / uart_write_bytes()：阻塞方式读取串口接收数据并原样写回，实现数据回显。

运行效果​

  • 通过外部 RS485 终端发送数据，板子会原样返回收到的数据。

    ESP32_Arduino_14

03_SD_Test​

本示例演示 SD 卡 挂载与文件系统访问。

硬件连接​

  • 使用 USB 线把板子接入电脑；
  • 插入 TF/SD 卡。

代码分析​

  • app_main()：示例入口，负责整体 SD 卡初始化与测试流程。
  • waveshare_sd_card_init()：封装 esp_vfs_fat_sdmmc_mount() 等底层接口，完成 SDMMC 主机配置与文件系统挂载。
  • waveshare_sd_card_test()：在挂载成功后执行读写测试，例如创建文件、写入数据并再次读取，验证 SD 卡工作是否正常。

运行效果​

  • 串口输出挂载成功信息及 SD 卡容量等参数。

    ESP32_IDF_04

04_RTC_Test​

本示例演示板载 PCF85063 的时间读写与闹钟中断功能。

硬件连接​

  • 使用 USB 线把板子接入电脑

代码分析​

  • Set_Time / Set_Alarm_Time：分别配置上电后 RTC 的初始时间和闹钟触发时间。
  • PCF85063A_Init()：初始化 PCF85063A，配置 I2C 通信参数。
  • PCF85063A_Set_All()：将 Set_Time 写入 RTC 寄存器，完成当前时间设置。
  • PCF85063A_Set_Alarm()：配置闹钟时间并写入到 RTC 对应寄存器。
  • PCF85063A_Enable_Alarm()：开启闹钟中断输出。
  • DEV_GPIO_INT()：将板载某个 GPIO 配置为中断输入并绑定 gpio_isr_handler 回调，用于接收 RTC 中断信号。
  • PCF85063A_Read_now()：周期性读取当前时间，配合 datetime_to_str() 转换为字符串输出到日志。

运行效果​

  • 串口周期性输出当前时间，并在闹钟触发时打印提醒。

    ESP32_IDF_03

05_IO_Test​

本示例验证隔离 IO 功能。

硬件连接​

  • 使用 USB 线把板子接入电脑；
  • 根据示例连接 DO/DI 引脚测试隔离功能。

    ESP32_Arduino_IO_Connect

代码分析​

  • DEV_Module_Init()：初始化板载外设与 CH422G 扩展芯片，为后续 DI/DO 测试做准备。
  • CH422G_od_output()：向 CH422G 的 OC 口输出不同值，驱动隔离 DO 引脚产生电平变化。
  • CH422G_io_input()：读取 CH422G 的 IO 状态，用于检测隔离 DI 引脚是否跟随预期变化。
  • DI_flag / num：统计成功次数与失败次数，当多次检测均失败时判定 DI/DO 异常。
  • LCD_init()：初始化 RGB LCD 显示，并返回 LVGL 显示对象指针。
  • example_lvgl_demo_ui()：在测试结束后运行简单 LVGL 界面，方便在屏幕上观察测试状态或提示信息。
  • lv_timer_handler()：在循环中周期调用，驱动 LVGL 刷新与动画。

运行效果​

  • 串口打印 DI 状态，观察 DO 端口电平跳变。

    ESP32_IDF_02

06_TWAItransmit​

本示例演示如何使用 ESP32-S3 的 TWAI (兼容 CAN) 接口发送数据。

硬件连接​

  • 使用 USB 线把板子接入电脑

  • 将 CAN 接口（CANH, CANL）连接到 CAN 总线

    ESP32_Arduino_CAN_Connect

代码分析​

  • app_main()：示例入口，循环调用 TWAI 发送接口。
  • waveshare_twai_init()：配置 CAN 相关 GPIO 与 TWAI 外设，内部完成 twai_driver_install() 等底层初始化，并通过扩展 IO 打开 CAN 通道。
  • waveshare_twai_transmit()：构造固定 ID 和数据内容的 CAN 帧，并按设定周期重复发送，用于与其他节点联调。

运行效果​

  • 另一 CAN 节点可接收到 ID 为 0x123 的报文。

    ESP32_IDF_05

    ESP32_Arduino_CN_01

07_TWAIreceive​

本示例演示如何使用 ESP32-S3 的 TWAI (兼容 CAN) 接口接收数据。

硬件连接​

  • 使用 USB 线把板子接入电脑

  • 将 CAN 接口（CANH, CANL）连接到 CAN 总线

    ESP32_Arduino_CAN_Connect

代码分析​

  • app_main()：示例入口，初始化 TWAI 接口并进入无限循环接收数据。
  • waveshare_twai_init()：与发送示例相同，完成 CAN 引脚与 TWAI 外设参数配置。
  • waveshare_twai_receive()：在内部调用 twai_receive() 等 API，从接收队列中读取报文；收到数据后解析 ID 与数据区并打印到串口。

运行效果​

  • 串口打印接收到的 CAN 报文 ID 与数据。

    ESP32_IDF_06

    ESP32_IDF_07

    ESP32_Arduino_CN_02

08_lvgl_Porting​

本示例演示 LVGL 图形库的移植与基础显示功能。

硬件连接​

  • 使用 USB 线把板子接入电脑；
  • 可触摸屏幕交互。

代码分析​

  • app_main()：示例入口，负责 RGB LCD 与 LVGL 的整体初始化流程。
  • waveshare_esp32_s3_rgb_lcd_init()：封装时钟、RGB 接口、背光以及 LVGL 显示驱动的初始化。
  • lvgl_port_lock() / lvgl_port_unlock()：获取并释放 LVGL 互斥锁，保证在单任务环境下安全调用 LVGL API。
  • lv_demo_widgets() / lv_demo_music()：根据配置运行官方 LVGL Demo，用于演示基础控件、动画与触摸交互效果。

运行效果​

  • 屏幕显示 LVGL 示例界面，支持触摸交互。

    lv_image

最后由 CQ793 于 更新