跳到主要内容

ESP-IDF 开发

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

ESP-IDF 入门教程​

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

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

配置开发环境​

本示例程序包基于 ESP-IDF 5.5.4 移植。请参考 微雪 ESP-IDF 入门教程 - 第 1 节 搭建环境 完成开发环境配置。

示例程序包结构​

ESP-IDF 示例程序位于示例程序包的 ESP-IDF/example 目录中。除各个独立工程外，该目录还包含两个共享组件：

example/
├── 01_IO_Test/
├── ...
├── 12_ETH_Web_CAM/
├── cam_web_common/
└── eth_w5500_common/

cam_web_common​

cam_web_common 封装摄像头和 Web 服务的公共功能，供 08_WIFI_Web_CAM 和 12_ETH_Web_CAM 复用，主要包含：

  • ESP32-S3-ETH 摄像头接口的 GPIO 定义和摄像头初始化；
  • GPIO8 摄像头使能控制；
  • JPEG 拍照和 MJPEG 视频流；
  • 图像质量、亮度、对比度、分辨率等参数控制；
  • HTTP 页面、状态查询和摄像头寄存器访问接口。

两个摄像头示例只分别处理 Wi-Fi 或 W5500 网络连接。摄像头初始化和 HTTP 服务由该共享组件实现，避免在两个工程中维护重复代码。

eth_w5500_common​

eth_w5500_common 封装 ESP32-S3-ETH 板载 W5500 的公共初始化流程，供 09_ETH_DHCP、10_ETH_StaticIP、11_ETH_MAC_DHCP_StaticIP 和 12_ETH_Web_CAM 复用，主要包含：

  • W5500 的 SPI2 和 GPIO 定义；
  • 可选的 W5500 硬件复位；
  • 20 MHz SPI 总线和 W5500 MAC、PHY 驱动初始化；
  • MAC 地址设置；
  • Ethernet 驱动与 esp_netif 网络接口关联。
W5500 信号ESP32-S3-ETH
MISOGPIO12
MOSIGPIO11
SCLKGPIO13
CSGPIO14
RSTGPIO9
INTGPIO10
保留共享组件目录

摄像头和以太网工程通过顶层 CMakeLists.txt 中的 EXTRA_COMPONENT_DIRS 引用同级共享组件。复制示例程序时，需要同时保留对应的 cam_web_common 或 eth_w5500_common 目录及其相对位置。若单独移动工程，需要同步复制共享组件，并修改工程中的 EXTRA_COMPONENT_DIRS 路径。

示例程序​

ESP-IDF 示例程序如下：

示例程序基础例程说明共享组件
01_IO_TestGPIO 引脚高低电平控制-
02_RGB_LED使用 RMT 控制 WS2812 RGB LED-
03_SD_Card使用 SDSPI 挂载 SD 卡并读写文件-
04_WiFi_AP设置 Wi-Fi AP 并显示接入设备信息-
05_WiFi_STA连接 Wi-Fi 并通过网页控制 GPIO18-
06_WIFI_DHCP通过 Wi-Fi 使用 DHCP 获取 IP 地址-
07_WIFI_StaticIP通过 Wi-Fi 使用静态 IP 地址-
08_WIFI_Web_CAM通过 Wi-Fi 传输摄像头图像cam_web_common
09_ETH_DHCP通过 W5500 使用 DHCP 获取 IP 地址eth_w5500_common
10_ETH_StaticIP通过 W5500 使用静态 IP 地址eth_w5500_common
11_ETH_MAC_DHCP_StaticIPDHCP 超时后切换为静态 IP 地址eth_w5500_common
12_ETH_Web_CAM通过 W5500 传输摄像头图像cam_web_common、eth_w5500_common

01_IO_Test​

本示例将 19 个可作为输出的 GPIO 初始化为低电平，再以 300 ms 的间隔逐个拉高和拉低。

运行效果​

串口监视器循环显示各 GPIO 的初始化和电平变化信息。

ESP-IDF GPIO 测试串口输出

02_RGB_LED​

本示例使用 ESP-IDF 原生 RMT 外设驱动 GPIO21 上的 WS2812 RGB LED。数据格式为 GRB、800 kHz，亮度为 50/255。主循环依次执行红、绿、蓝填充和白、红、蓝剧院追逐效果。

运行效果​

RGB LED 按 50 ms 的步骤间隔显示填充和追逐效果。

RGB LED 运行效果

03_SD_Card​

本示例使用 ESP-IDF 的 SDSPI 和 FAT VFS 驱动挂载板载 Micro SD 卡。程序以追加模式向 /waveshare.txt 写入 Hello world from Waveshare，列出根目录内容，再读取并打印该文件。

提示

本示例默认仅支持 FAT32 文件系统，建议使用 16 GB 或 32 GB 的 SD 卡。不支持 exFAT 或 NTFS。64 GB 及以上的 SDXC 存储卡通常默认采用 exFAT 格式，需要备份数据后重新格式化为 FAT32 才能使用。格式化会清除存储卡中的全部数据。

SD 卡信号ESP32-S3-ETH
MISOGPIO5
MOSIGPIO6
SCLKGPIO7
CSGPIO4

工程已在 sdkconfig.defaults 中启用 FATFS 长文件名支持。SD 卡需要使用 FAT 或 FAT32 文件系统。

Micro SD 卡长文件名支持配置

Micro SD 卡硬件连接

运行效果​

串口监视器显示 SD 卡容量、文件写入结果、根目录文件列表和文件内容。

SD 卡示例

04_WiFi_AP​

本示例创建 WPA2 SoftAP，SSID 为 ESP32-S3-ETH，密码为 88888888。客户端连接时打印 MAC 地址，DHCP 地址分配完成后打印客户端 IP 地址，客户端断开时打印提示。

ESP-IDF Wi-Fi AP 运行结果

05_WiFi_STA​

本示例连接 Waveshare-AP，并在 80 端口启动 HTTP 服务。访问 /H 可将 GPIO18 设置为高电平，访问 /L 可将 GPIO18 设置为低电平。

使用其他网络时，修改 main/wifi_sta.c 中的 WIFI_SSID 和 WIFI_PASSWORD。

提示

有条件的同学，可以参考右图串上一个 LED 灯，实测查看 GPIO18 的高低电平状态，或者用万用表测量。

GPIO18 接线图

ESP-IDF Wi-Fi STA 连接和服务器地址

GPIO18 低电平网页状态

GPIO18 高电平网页状态

GPIO18 恢复低电平网页状态

06_WIFI_DHCP​

本示例连接 Waveshare-AP，由路由器通过 DHCP 分配 IPv4 地址。连接断开后，程序会自动重新连接。

使用其他网络时，修改 main/wifi_dhcp.c 中的 Wi-Fi 参数。

ESP-IDF Wi-Fi DHCP 运行结果

07_WIFI_StaticIP​

本示例连接 Waveshare-AP，并使用以下静态网络参数：

  • IP 地址：192.168.196.100
  • 网关：192.168.196.1
  • 子网掩码：255.255.255.0
  • DNS：192.168.196.1

示例源代码中的默认密码为 88888888。使用前需要确认路由器位于 192.168.196.0/24 网段，并确认 192.168.196.100 未被其他设备占用。

ESP-IDF Wi-Fi 静态 IP 运行结果

08_WIFI_Web_CAM​

本示例通过 Wi-Fi 连接网络，使用 cam_web_common 初始化摄像头并启动 Web 服务。网页支持 MJPEG 视频流、单帧拍照、图像质量、亮度和对比度等设置。

配置 Wi-Fi​

运行以下命令：

idf.py menuconfig

在 "Wi-Fi camera configuration" 中配置 SSID 和密码。连接成功后，访问串口日志输出的 URL。

摄像头硬件连接

摄像头接口​

摄像头信号ESP32-S3-ETH
ENABLEGPIO8
VSYNCGPIO1
HREFGPIO2
XCLKGPIO3
PCLKGPIO39
SIOD (SDA)GPIO48
SIOC (SCL)GPIO47
D7GPIO18
D6GPIO15
D5GPIO38
D4GPIO40
D3GPIO42
D2GPIO46
D1GPIO45
D0GPIO41

摄像头 Web 页面

09_ETH_DHCP​

本示例通过 eth_w5500_common 初始化 W5500，MAC 地址设置为 DE:AD:BE:EF:FE:ED。程序等待 DHCP 分配地址；如果 60 秒内未获得 IP 地址，则输出失败信息并停止等待。

以太网硬件连接

ESP-IDF W5500 DHCP 运行结果

10_ETH_StaticIP​

本示例通过 W5500 使用以下静态网络参数：

  • IP 地址：192.168.9.200
  • 网关和 DNS：192.168.9.1
  • 子网掩码：255.255.255.0
  • MAC 地址：DE:AD:BE:EF:FE:ED

ESP-IDF W5500 静态 IP 运行结果

11_ETH_MAC_DHCP_StaticIP​

本示例启动时对 W5500 执行硬件复位，并尝试通过 DHCP 获取 IP 地址。如果 60 秒内未获得地址，则切换为以下静态网络参数：

  • IP 地址：192.168.1.177
  • 网关和 DNS：192.168.1.1
  • 子网掩码：255.255.255.0
  • MAC 地址：DE:AD:BE:EF:FE:ED

ESP-IDF W5500 DHCP 回退静态 IP 运行结果

12_ETH_Web_CAM​

本示例同时使用 eth_w5500_common 和 cam_web_common。程序先初始化摄像头和 W5500，等待 DHCP 获取 IP 地址，再启动摄像头 Web 服务。

连接成功后，串口监视器输出访问 URL。在同一网络的浏览器中打开该 URL，可使用 MJPEG 视频流、拍照和图像参数设置功能。

以太网摄像头和 PoE 模块连接

以太网摄像头页面

文档反馈​

如在使用过程中遇到问题，欢迎留言反馈。