arduino-esp32 以太网实战指南从 LAN8720/TLK110 RMII 到 W5500 SPI 的完整接入方案【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读本文围绕 Arduino core for ESP32arduino-esp32的Ethernet 库展开系统讲解如何在 ESP32 系列 SoC 上通过 RMII 或 SPI 接口接入以太网 PHY 芯片LAN8720、TLK110、W5500 等。你将掌握官方示例中完整的引脚宏配置、事件驱动编程模型、ETH.begin()的多种调用形式与底层实现原理并能直接复制运行文中代码完成有线网络接入。文中所有示例与源码证据均来自当前仓库的 libraries/Ethernet 目录及 tests/validation/ethernet 验证测试。文档现状与本文定位官方 API 文档 docs/en/api/ethernet.rst 目前标注为work in progressAbout一节明确说明该章节内容仍待补充并邀请开发者通过 docs/en/contributing.rst 的贡献指南参与完善。文档的Examples一节是现有最核心的内容——它通过literalinclude直接内嵌了 ETH_LAN8720 与 ETH_TLK110 两个可编译示例。因此本文以这两个官方示例为骨架结合仓库中 ETH.h / ETH.cpp 的实现细节、W5500 示例、WiFi 桥接示例 以及 以太网验证测试将文档中缺失的 About补全为一份可查证、可运行的实战资料。一、Ethernet 库总览能做什么、支持哪些 PHY从 library.properties 可确认该库的定位Enables network connection (local and Internet) using the ESP32 Ethernet——它使 ESP32 能够实例化 Server、Client并通过以太网收发 UDP 报文IP 地址可静态指定或通过 DHCP 获取同时支持 DNS 管理。结合 ETH.h 中eth_phy_type_t枚举当前库按编译配置支持以下 PHY 芯片接口类型PHY 类型枚举说明RMIIESP32 内置 EMACETH_PHY_GENERICESP-IDF 5.4 的通用驱动ETH_PHY_JL1101为其别名RMIIETH_PHY_LAN8720最常见的低成本 RMII PHYOlimex 等开发板RMIIETH_PHY_TLK110即ETH_PHY_IP101IP101 系列见 ETH.h 的宏定义RMIIETH_PHY_RTL8201/ETH_PHY_DP83848瑞昱 / TI 经典 RMII PHYRMIIETH_PHY_KSZ8041/ETH_PHY_KSZ8081Microchip KSZ80xx 系列RMIIETH_PHY_LAN867X需 ESP-IDF 提供esp_eth_phy_lan867x.h时才启用条件编译SPIETH_PHY_W5500WIZnet 硬协议栈芯片最常用的 SPI 以太网方案SPIETH_PHY_DM9051/ETH_PHY_KSZ8851其他 SPI 接口 PHY同样按头文件是否存在条件编译注意上表中 RMII 类 PHY 需要CONFIG_ETH_USE_ESP32_EMAC配置开启即使用芯片内置以太网 MACSPI 类则依赖CONFIG_ETH_SPI_ETHERNET_*系列配置。库顶层还受CONFIG_ETH_ENABLED保护ETH.h未启用以太网时整个头文件为空。二、开始之前理解引脚宏配置约定两个官方示例LAN8720 / TLK110都用同一套宏 默认值模式组织硬件配置。核心约定是在#include ETH.h之前通过#define定义ETH_PHY_*系列宏示例统一用#ifndef ETH_PHY_MDC包裹默认值这样用户在pins_arduino.h中预先定义好的板级配置不会被示例覆盖定义齐全后setup()里直接调用无参的ETH.begin()即可ETH.h 中的无参begin()会读取这些宏自动路由到对应重载。ETH.h 头部注释给出了三组可放入pins_arduino.h的典型配置样例// Example RMII LAN8720 (Olimex, etc.) #define ETH_PHY_TYPE ETH_PHY_LAN8720 #define ETH_PHY_ADDR 0 #define ETH_PHY_MDC 23 #define ETH_PHY_MDIO 18 #define ETH_PHY_POWER -1 #define ETH_CLK_MODE ETH_CLOCK_GPIO0_IN // Example RMII ESP32_Ethernet_V4 #define ETH_PHY_TYPE ETH_PHY_TLK110 #define ETH_PHY_ADDR 1 #define ETH_PHY_MDC 23 #define ETH_PHY_MDIO 18 #define ETH_PHY_POWER -1 #define ETH_CLK_MODE ETH_CLOCK_GPIO0_OUT // Example SPI using ESP-IDFs driver #define ETH_PHY_TYPE ETH_PHY_W5500 #define ETH_PHY_ADDR 1 #define ETH_PHY_CS 15 #define ETH_PHY_IRQ 4 #define ETH_PHY_RST 5 #define ETH_PHY_SPI_HOST SPI2_HOST #define ETH_PHY_SPI_SCK 14 #define ETH_PHY_SPI_MISO 12 #define ETH_PHY_SPI_MOSI 13各宏含义与取值要点宏含义备注ETH_PHY_TYPEPHY 芯片类型取值见上文eth_phy_type_t枚举ETH_PHY_ADDRPHY 的 MDIO 地址可用ETH_PHY_ADDR_AUTO即ESP_ETH_PHY_ADDR_AUTO启用自动探测地址小于该值会被begin()拒绝见 ETH.cppETH_PHY_MDC/ETH_PHY_MDIO管理接口时钟/数据引脚RMII经digitalPinToGPIONumber()转换后写入 SMI 配置ETH_PHY_POWERPHY 复位/电源引脚传-1表示未使用非 -1 时该引脚会被纳入 pin 总线管理ETH_CLK_MODERMII 参考时钟模式ESP32 上为ETH_CLOCK_GPIO0_IN/OUT、ETH_CLOCK_GPIO16_OUT、ETH_CLOCK_GPIO17_OUTESP32-P4 上为 EMAC 时钟枚举ETH_PHY_CS/IRQ/RSTSPI 方案片选/中断/复位SPICS 必填IRQ 可选见下文无 IRQ 说明ETH_PHY_SPI_HOST及ETH_PHY_SPI_SCK/MISO/MOSISPI 外设与引脚IDF SPI 方案引脚缺省为 -1 时复用begin()传入的值三、官方示例一LAN8720RMII 接入ETH_LAN8720.ino 展示的是以太网事件的完整用法其硬件默认值针对典型 RMII 板卡如 Olimex#include Arduino.h #ifndef ETH_PHY_MDC #define ETH_PHY_TYPE ETH_PHY_LAN8720 #if CONFIG_IDF_TARGET_ESP32 #define ETH_PHY_ADDR 0 #define ETH_PHY_MDC 23 #define ETH_PHY_MDIO 18 #define ETH_PHY_POWER -1 #define ETH_CLK_MODE ETH_CLOCK_GPIO0_IN #elif CONFIG_IDF_TARGET_ESP32P4 #define ETH_PHY_ADDR 0 #define ETH_PHY_MDC 31 #define ETH_PHY_MDIO 52 #define ETH_PHY_POWER 51 #define ETH_CLK_MODE EMAC_CLK_EXT_IN #endif #endif #include ETH.h这段配置的关键点通过CONFIG_IDF_TARGET_ESP32/CONFIG_IDF_TARGET_ESP32P4区分芯片平台为不同 SoC 提供不同的默认引脚与时钟模式说明该库同时支持经典 ESP32 与新一代 ESP32-P4的内置 EMAC经典 ESP32 的 RMII 数据引脚是固定的ETH_RMII_TX_EN21、ETH_RMII_TX019、ETH_RMII_TX122、ETH_RMII_RX025、ETH_RMII_RX1_EN26、ETH_RMII_CRS_DV27见 ETH.h因此只需配置 MDC/MDIO 与时钟ESP32-P4 的 RMII 引脚通过pins_arduino.h可覆盖默认值为 TX_EN49、TX034、TX135、RX029、RX1_EN30、CRS_DV28、RMII_CLK50ETH.h。启动流程本身极简static bool eth_connected false; void setup() { Serial.begin(115200); Network.onEvent(onEvent); ETH.begin(); } void loop() { if (eth_connected) { testClient(google.com, 80); } delay(10000); }示例随后用testClient()发起一个原始 HTTP GET 请求来验证连通性。需要特别注意的是它使用NetworkClient而非旧版WiFiClient这正是当前 Arduino-ESP32 网络抽象层的统一客户端类型与Network.onEvent()配套使用。四、官方示例二TLK110显式传参的 RMII 接入ETH_TLK110.ino 与 LAN8720 示例的差异在于两点一是 PHY 类型与引脚默认值不同ETH_PHY_TLK110、ETH_PHY_ADDR 31、ETH_PHY_POWER 17ESP32-P4 下地址为 1二是它在setup()中显式传参调用begin()ETH.begin(ETH_PHY_TYPE, ETH_PHY_ADDR, ETH_PHY_MDC, ETH_PHY_MDIO, ETH_PHY_POWER, ETH_CLK_MODE);对应的重载原型为ETH.hbool begin(eth_phy_type_t type, int32_t phy_addr, int mdc, int mdio, int power, eth_clock_mode_t clk_mode);该重载仅在CONFIG_ETH_USE_ESP32_EMAC下可用是 RMII 方案的标准入口。从 ETH.cpp 可以梳理出它在底层依次完成的核心调用链Network.begin()初始化网络抽象层并注册 ETH 事件处理器通过ETH_EMAC_DEFAULT_CONFIG()取得默认 EMAC 配置按clock_mode映射 GPIO0/GPIO16/GPIO17 或外部输入时钟经典 ESP32 分支见 ETH.cppesp_eth_mac_new_esp32()创建 MAC 对象esp_eth_phy_new_lan87xx()/esp_eth_phy_new_ip101()等按type创建对应 PHY 对象ETH.cppesp_eth_driver_install()安装驱动、esp_netif_new()创建网络接口、esp_eth_new_netif_glue()esp_netif_attach()将驱动挂接到 TCP/IP 协议栈esp_eth_start()启动以太网状态机最后delay(50)等待 DHCP 进入良好状态注释中注明这是为了规避历史 issue #5733所有占用的 GPIO 通过perimanSetPinBus()登记到 pin 总线管理器end()或总线释放时会自动回收。整个流程就是MAC PHY netif glue 协议栈的 ESP-IDF 标准装配Arduino 层把它封装成了一个布尔返回的begin()。五、事件驱动模型Arduino 网络事件机制两个官方示例的核心都放在onEvent(arduino_event_id_t event)回调里setup()中通过Network.onEvent(onEvent)注册。示例注释明确警告该回调运行在独立的 FreeRTOS 任务线程中因此回调内应避免耗时阻塞操作。回调覆盖的以太网事件生命周期如下事件含义示例中的处理ARDUINO_EVENT_ETH_START以太网接口启动打印日志并在此设置主机名ETH.setHostname(esp32-ethernet)——注释说明主机名须在接口启动后、DHCP 之前设置因此放在事件线程里最合适ARDUINO_EVENT_ETH_CONNECTED物理链路已连接网线插入、协商完成打印日志ARDUINO_EVENT_ETH_GOT_IP通过 DHCP 获取到 IP打印ETH对象会输出 IP/网关/掩码等置eth_connected trueARDUINO_EVENT_ETH_LOST_IP丢失 IP置eth_connected falseARDUINO_EVENT_ETH_DISCONNECTED链路断开置eth_connected falseARDUINO_EVENT_ETH_STOP接口停止打印日志置eth_connected false从源码看这一事件流是由 ETH.cpp 的_onEthEvent()完成的它接收 ESP-IDF 的ETHERNET_EVENT_*原始事件映射为ARDUINO_EVENT_ETH_*枚举并通过Network.postEvent()派发到用户的onEvent。同时onEthConnected()ETH.cpp会在链路连通后按需为接口创建 IPv6 链路本地地址esp_netif_create_ip6_linklocal()这说明IPv6 支持默认是开启的CONFIG_LWIP_IPV6条件下。六、扩展到 SPI 以太网W5500 的两种接线方式文档示例之外仓库还提供了两个 W5500 示例分别对应两种 SPI 接入路径正好补全About 缺失的 SPI 部分。方式一使用 Arduino SPI 驱动ETH_W5500_Arduino_SPI.ino#include SPI.h #define ETH_PHY_TYPE ETH_PHY_W5500 #define ETH_PHY_ADDR 1 #define ETH_PHY_CS 15 #define ETH_PHY_IRQ 4 #define ETH_PHY_RST 5 #define ETH_SPI_SCK 14 #define ETH_SPI_MISO 12 #define ETH_SPI_MOSI 13 void setup() { SPI.begin(ETH_SPI_SCK, ETH_SPI_MISO, ETH_SPI_MOSI); ETH.begin(ETH_PHY_TYPE, ETH_PHY_ADDR, ETH_PHY_CS, ETH_PHY_IRQ, ETH_PHY_RST, SPI); }对应重载ETH.hbool begin(eth_phy_type_t type, int32_t phy_addr, int cs, int irq, int rst, SPIClass spi, uint8_t spi_freq_mhz ETH_PHY_SPI_FREQ_MHZ);该路径由 Arduino 的SPIClass接管 SPI 总线库通过自定义 SPI 驱动回调_eth_spi_read/_eth_spi_write见 ETH.cpp与 W5500 通信。从实现看W5500 的 SPI 帧格式是16 位命令 8 位地址DM9051 与 KSZ8851 则使用各自的命令编码——这些细节对用户透明。方式二使用 ESP-IDF SPI 驱动ETH_W5500_IDF_SPI.ino#define ETH_PHY_TYPE ETH_PHY_W5500 #define ETH_PHY_ADDR 1 #define ETH_PHY_CS 15 #define ETH_PHY_IRQ 4 #define ETH_PHY_RST 5 #define ETH_PHY_SPI_HOST SPI2_HOST #define ETH_PHY_SPI_SCK 14 #define ETH_PHY_SPI_MISO 12 #define ETH_PHY_SPI_MOSI 13 ETH.begin(ETH_PHY_TYPE, ETH_PHY_ADDR, ETH_PHY_CS, ETH_PHY_IRQ, ETH_PHY_RST, ETH_PHY_SPI_HOST, ETH_PHY_SPI_SCK, ETH_PHY_SPI_MISO, ETH_PHY_SPI_MOSI);对应重载ETH.h允许指定spi_host_device_t与 SCK/MISO/MOSI 引脚库内部调用spi_bus_initialize()初始化总线ETH.cppSPI 频率默认ETH_PHY_SPI_FREQ_MHZ 20MHzETH.h可通过最后一个参数覆盖。双以太网与无 IRQ 轮询模式两个 W5500 示例均内置USE_TWO_ETH_PORTS开关展示单 SPI 总线挂接两个 W5500 端口的能力第二个端口用ETHClass ETH1(1)实例化索引 1共享 SPI 时ETH1.begin()不再传 SPI 引脚ETH1.begin(ETH1_PHY_TYPE, ETH1_PHY_ADDR, ETH1_PHY_CS, ETH1_PHY_IRQ, ETH1_PHY_RST, ETH_PHY_SPI_HOST);从源码看库支持最多 3 个以太网端口NUM_SUPPORTED_ETH_PORTS 3多端口时各接口的 netif 路由优先级按索引递减route_prio - _eth_index * 5MAC 地址会在基址上按索引递增派生ETH.cpp。另外W5500 支持不接 IRQ 引脚的轮询模式CS 为必填IRQ 可传-1此时需在begin()前用setPollPeriod(poll_period_ms)设置轮询周期默认 10 ms见 ETH.cpp 的构造函数初始化。相关条件编译开关ETH_SPI_SUPPORTS_NO_IRQ定义于 ETH.h。七、进阶示例有线 Wi-Fi 双通道桥接ETH_WIFI_BRIDGE.ino 演示了以太网与 Wi-Fi 软 AP 的协同W5500 接有线网络同时开启 Wi-Fi AP通过NAPT网络地址端口转换让无线客户端共享有线出口WiFi.AP.begin(); WiFi.AP.config(ap_ip, ap_ip, ap_mask, ap_leaseStart, ap_dns); WiFi.AP.create(AP_SSID, AP_PASS); ... ETH.begin(ETH_TYPE, ETH_ADDR, ETH_CS, ETH_IRQ, ETH_RST, SPI);事件回调在ARDUINO_EVENT_ETH_GOT_IP时调用WiFi.AP.enableNAPT(true)开启转发在LOST_IP/DISCONNECTED时关闭。这展示了该网络抽象层对多网络接口统一管理的能力——同一套onEvent机制同时处理ARDUINO_EVENT_ETH_*与ARDUINO_EVENT_WIFI_AP_*事件无线客户端STAIPASSIGNED等事件也一并在回调中可观测。八、ETH 类 API 深度解析结合 ETH.h 与 ETH.cppETHClass继承自NetworkInterface除网络接口通用能力外还提供以下专有 API运行期查询接口bool fullDuplex() const; // 当前是否全双工ETH_CMD_G_DUPLEX_MODE uint16_t linkSpeed() const; // 返回 10 或 100Mbps bool autoNegotiation() const; // 当前是否开启自动协商 uint32_t phyAddr() const; // 实际 PHY 地址 esp_eth_handle_t handle() const; // 底层 ESP-IDF 驱动句柄这些方法通过esp_eth_ioctl()读取未初始化时返回 0/falseETH.cpp。参数设置接口须在 begin() 之前调用bool setFullDuplex(bool on); // 设置全/半双工 bool setLinkSpeed(uint16_t speed); // 仅支持 10 或 100其他值直接报错 bool setAutoNegotiation(bool on); // 开关自动协商 void setTaskStackSize(size_t size); // 接收任务栈大小默认 4096 void setPollPeriod(uint32_t poll_period_ms); // W5500 无 IRQ 时轮询周期默认 10ms实现上的关键约束三个set*方法在_eth_started之后调用会打印This method must be called before ETH.begin()并返回 false且当自动协商开启时这些手动设置不会生效——ETH.cpp 中只有在!_auto_negotiation时才会在begin()流程内真正下发自动协商关闭、双工模式和链路速率。因此固定速率的正确写法是ETH.setAutoNegotiation(false); ETH.setFullDuplex(true); ETH.setLinkSpeed(100); ETH.begin();组播与 MAC 过滤ESP-IDF ≥ 5.5bool addMacFilter(uint8_t *mac_addr); // 添加单播 MAC 过滤 bool removeMacFilter(uint8_t *mac_addr); bool addMulticastFilter(IPAddress address); // 按组播 IP 推导 MAC01:00:5E:xx:xx:xx bool removeMulticastFilter(IPAddress address); bool receiveAllMulticast(bool on); // 默认开启begin() 成功后自动调用addMulticastFilter()会校验地址首字节须在 224~239 范围内并按 IPv4 组播 MAC 映射规则计算目的地址ETH.cpp。九、验证测试这些能力如何被自动化检验仓库的 tests/validation/ethernet 目录提供了覆盖上述功能的硬件验证测试其 README.md 列出的测试矩阵包括测试函数验证点test_eth_link_up30 秒内链路连接并拿到 DHCP IPtest_eth_ip_valid分配的 IP 非零test_eth_mac_addressMAC 字符串为 17 字符、含 5 个冒号test_eth_link_speed链路速率必须是 10 或 100 Mbps并 smoke-checkfullDuplex()test_eth_gateway/test_eth_subnet网关非零、子网首字节为 255test_eth_dns_server/test_eth_dns_resolutionDNS 已分配且能解析pool.ntp.orgtest_eth_tcp_gateway向网关:80 或 DNS:53 发起 TCP 连接test_eth_static_ip配置静态 IP192.168.200.250验证后恢复 DHCP测试代码在 ethernet.ino 中通过事件驱动方式等待ARDUINO_EVENT_ETH_CONNECTED/ARDUINO_EVENT_ETH_GOT_IP与官方示例的回调模型完全一致。测试要求真实硬件RMII 或 SPI PHY不支持 Wokwi/QEMU 模拟。这份测试清单相当于一份验收标准可作为判断自己的以太网接线与配置是否正确的参照。十、快速排错与最佳实践小结先确认编译配置RMII 方案必须启用CONFIG_ETH_USE_ESP32_EMACSPI 方案须启用对应的CONFIG_ETH_SPI_ETHERNET_*整体须CONFIG_ETH_ENABLED——否则ETH.h内容为空编译会直接失败。PHY 地址要正确地址写错时begin()虽可能成功但链路不通可改用ETH_PHY_ADDR_AUTO自动探测库对非法负地址会拒绝启动并打印提示。时钟模式按板卡接线选择LAN8720 通常用ETH_CLOCK_GPIO0_IN外部晶振或ETH_CLOCK_GPIO0_OUT时钟接错是 RMII 最常见的插线无反应原因。RMII 数据引脚不可更改经典 ESP32 的 6 根 RMII 数据线是固定 GPIO21/19/22/25/26/27只能调整 MDC/MDIO 和时钟。配置宏尽量下沉到pins_arduino.h官方示例的#ifndef保护正是为了兼容板级预定义见 ETH.h 注释。回调线程安全onEvent在 FreeRTOS 任务中执行只做标志位设置与日志输出网络 I/O 放到loop()。多接口场景第二个以太网口用ETHClass ETH1(1)共享 SPI 时省略 SPI 引脚接口路由优先级会自动按索引调整。结语尽管官方文档 docs/en/api/ethernet.rst 的 About 部分仍在建设中但仓库中的 Ethernet 库、5 个官方示例与 验证测试 已经构成了一套完整可用的有线网络方案从 RMII 的 LAN8720/TLK110 到 SPI 的 W5500从单端口到三端口从纯以太网到与 Wi-Fi 的 NAPT 桥接。本文所述的所有配置宏、API 行为与调用链均可直接在对应源码文件中查证你可以据此在自己的板卡上完成以太网接入并进一步为官方文档的 About 章节贡献内容。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考