ESP-IDF 5.0 网络子系统升级指南

ESP-IDF 5.0 网络子系统升级指南

esp-idf Espressif IoT Development Framework. Official development framework for Espressif SoCs. 项目地址: https://gitcode.com/gh_mirrors/es/esp-idf

前言

ESP-IDF 5.0 版本对网络子系统进行了多项重要改进和优化，本文将详细介绍 Wi-Fi 和以太网相关的重要变更点，帮助开发者顺利完成版本迁移。这些变更主要集中在 API 接口的优化、功能增强和代码简化等方面。

Wi-Fi 子系统变更

ESP-NOW 接收回调函数改进

在 ESP-IDF 5.0 中，esp_now_recv_cb_t 回调函数的第一个参数类型从简单的 const uint8_t *mac_addr 升级为更丰富的 esp_now_recv_info_t 结构体。这一变更带来了三个重要改进：

1. 源地址获取：通过 src_addr 成员可以获取发送方的 MAC 地址，功能等同于之前的 mac_addr 参数

2. 目标地址识别：新增的 des_addr 成员可以区分单播和广播数据包，这在安全策略配置中特别有用

3. 接收控制信息：rx_ctrl 成员提供了数据包接收的额外控制信息

迁移建议：

• 需要重新定义 ESP-NOW 接收回调函数
• 使用 src_addr 替代原有的 mac_addr
• 利用 des_addr 实现更精细的数据包处理逻辑

以太网子系统变更

eth_ioctl API 规范化

esp_eth_ioctl() API 在 5.0 版本中进行了重要改进，解决了之前版本中的类型安全问题：

1. 问题背景：

   • 之前版本允许直接传递 int/bool 类型参数
   • 需要强制类型转换为 void* 以避免编译器警告
   • 缺乏明确的文档说明

2. 新规范：

   • 必须传递指向特定数据类型的指针
   • 设置配置时传递写入数据的指针
   • 获取配置时传递存储结果的指针

示例代码：

// 设置双工模式
eth_duplex_t new_duplex_mode = ETH_DUPLEX_HALF;
esp_eth_ioctl(eth_handle, ETH_CMD_S_DUPLEX_MODE, &new_duplex_mode);

// 获取当前双工模式
eth_duplex_t duplex_mode;
esp_eth_ioctl(eth_handle, ETH_CMD_G_DUPLEX_MODE, &duplex_mode);

PHY 驱动更新

KSZ8041/81 和 LAN8720 驱动程序进行了扩展，支持更多同系列设备：

1. 驱动合并：

   • 移除 esp_eth_phy_new_ksz8041() 和 esp_eth_phy_new_ksz8081()
   • 统一使用 esp_eth_phy_new_ksz80xx()
   • 移除 esp_eth_phy_new_lan8720()
   • 统一使用 esp_eth_phy_new_lan87xx()

2. 优势：

   • 提高代码复用率
   • 简化驱动维护
   • 支持更多兼容设备

自动事件处理

网络接口的默认事件处理变得更加智能：

1. 移除函数：

   • esp_eth_set_default_handlers()
   • esp_eth_clear_default_handlers()

2. 新机制：

   • IP 层默认事件处理程序自动注册
   • 开发者只需关注自定义事件处理

最佳实践：

• 确保以太网驱动和网络接口完全初始化后再注册事件处理程序
• 如果没有特殊需求，可以完全移除相关代码

SPI 以太网模块简化

SPI 以太网模块的初始化流程大幅简化：

1. 主要改进：

   • 不再需要手动调用 spi_bus_add_device()
   • SPI 设备由驱动内部自动管理

2. 配置结构更新：

   • DM9051、W5500 和 KSZ8851SNL 配置结构新增 SPI 时序参数
   • 默认配置宏接受更多参数

优势：

• 减少初始化代码量
• 提高易用性
• 保持配置灵活性

MAC 实例创建 API 重构

以太网 MAC 实例创建 API 进行了重要重构：

1. 参数变化：

   • 从单一配置参数改为两个独立参数
   • 分别处理厂商特定配置和通用驱动配置

2. 影响范围：

   • 内部 ESP32 MAC (esp_eth_mac_new_esp32())
   • 外部 MAC 设备 (KSZ8851SNL、DM9051、W5500)

优势：

• 配置更加清晰
• 提高代码可维护性
• 便于扩展新功能

TCP/IP 适配器迁移指南

网络堆栈初始化

1. 替换方案：

   • tcpip_adapter_init() → esp_netif_init()
   • 新增 esp_netif_deinit() 用于反初始化

2. 注意事项：

   • esp_netif_init() 返回标准错误码
   • 头文件变更为 #include "esp_netif.h"

网络接口创建

从静态定义改为显式创建：

1. 主要变化：

   • 需要显式调用创建函数
   • 三种默认接口创建函数：
     • esp_netif_create_default_wifi_sta()
     • esp_netif_create_default_wifi_ap()
     • 以太网接口创建函数

2. 优势：

   • 更灵活的接口管理
   • 支持更多网络拓扑

API 对应关系

所有 tcpip_adapter API 都有对应的 esp-netif 版本：

1. 功能分类：

   • 设置/获取函数
   • DHCP 相关函数
   • DNS 相关函数
   • IP 地址相关函数

2. 特殊函数迁移：

   • tcpip_adapter_get_sta_list() → esp_wifi_ap_get_sta_list_with_ip()
   • 更通用的 esp_netif_dhcps_get_clients_by_mac()

IP 地址处理建议

1. 打印优化： 推荐使用 ESP-NETIF 提供的宏：

   ESP_LOGI(TAG, "got ip:" IPSTR, IP2STR(&event->ip_info.ip));
   

   替代 LwIP 的：

   ESP_LOGI(TAG, "got ip:%s", ip4addr_ntoa(&event->ip_info.ip));
   

2. 结构体使用：

   • 建议使用 esp-netif 定义的 IP 结构体
   • LwIP 结构体仍然兼容但不再推荐

总结

ESP-IDF 5.0 的网络子系统升级带来了多项重要改进，包括：

1. API 更加规范和类型安全
2. 初始化流程简化
3. 功能扩展和驱动增强
4. 更好的代码组织结构

开发者应按照本文指南逐步更新代码，特别注意类型安全和新的初始化流程。这些变更虽然需要一定的迁移工作，但将带来更稳定、更易维护的代码基础。

esp-idf Espressif IoT Development Framework. Official development framework for Espressif SoCs. 项目地址: https://gitcode.com/gh_mirrors/es/esp-idf