跳转到内容
ESPHome - 让智能家居更简单2026.7.0

Ethernet 组件

此 ESPHome 组件为 ESP32 和 RP2040 开发板启用有线 Ethernet 连接。

  • ESP32：支持 RMII PHY 芯片（LAN8720、RTL8201 等）和 SPI Ethernet 芯片（W5500、DM9051、ENC28J60）。
  • RP2040/RP2350：支持 SPI/PIO Ethernet 芯片（W5100、W5500、W6100、W6300、ENC28J60）。

此组件和 Wi-Fi 组件不能同时使用，即使两者在硬件上都可用。

# Example configuration entry for RMII chips
ethernet:
  type: LAN8720
  mdc_pin: GPIOXX
  mdio_pin: GPIOXX
  clk:
    pin: GPIOXX
    mode: CLK_EXT_IN
  phy_addr: 0


  # Optional manual IP
  manual_ip:
    static_ip: 10.0.0.42
    gateway: 10.0.0.1
    subnet: 255.255.255.0
# Example configuration entry for the GENERIC RGMII PHY (ESP32-S31)
ethernet:
  type: GENERIC
  mdc_pin: GPIO5
  mdio_pin: GPIO6
  power_pin: GPIO7   # the PHY reset pin
# Example configuration entry for SPI chips (ESP32)
ethernet:
  type: W5500
  clk_pin: GPIOXX
  mosi_pin: GPIOXX
  miso_pin: GPIOXX
  cs_pin: GPIOXX
  interrupt_pin: GPIOXX
  reset_pin: GPIOXX
# Example configuration entry for SPI chips (RP2040 Pico)
ethernet:
  type: W5500
  clk_pin: 18
  mosi_pin: 19
  miso_pin: 16
  cs_pin: 17
  interrupt_pin: 21
  reset_pin: 20

配置变量

Section titled “配置变量”

  • type (Required, string): LAN 芯片组/phy 的类型。

    支持的芯片组有：

    • LAN8720 (RMII, ESP32 only)
    • RTL8201 (RMII, ESP32 only)
    • DP83848 (RMII, ESP32 only)
    • IP101 (RMII, ESP32 only)
    • JL1101 (RMII, ESP32 only)
    • KSZ8081 (RMII, ESP32 only)
    • KSZ8081RNA (RMII, ESP32 only)
    • W5100 (SPI, RP2040 only)
    • W5500 (SPI, ESP32 and RP2040)
    • OPENETH (QEMU, ESP32 only)
    • DM9051 (SPI, ESP32 only)
    • ENC28J60 (SPI, 10Mbps, ESP32 and RP2040)
    • W6100 (SPI, RP2040/RP2350 only)
    • W6300 (PIO QSPI, RP2040/RP2350 only)
    • LAN8670 (RMII, ESP32 only)
    • GENERIC (RGMII, ESP32-S31 only)
    • YT8531 (RGMII, ESP32-S31 only)

RMII 配置变量

Section titled “RMII 配置变量”

  • mdc_pin (Required, Pin): 开发板的 MDC 引脚。 通常为 GPIO23。

  • mdio_pin (Required, Pin): 开发板的 MDIO 引脚。 通常为 GPIO18。

  • clk (Required, mapping):

    • pin (Required, Pin): RMII 时钟引脚。

    • mode (Required, string): 数据线的时钟模式。有关更多详细信息，请参阅你的开发板数据手册。必须是以下值之一：

      • CLK_EXT_IN - 外部时钟
      • CLK_OUT - 内部时钟

  • phy_addr (Optional, int): Ethernet 控制器的 PHY 地址类型。默认为 0。

  • phy_registers (Optional, mapping): Ethernet 初始化后要设置的任意 PHY 寄存器值。

    • address (Required, hex): 以十六进制数字表示的寄存器地址（例如地址 16 写作 0x10）
    • value (Required, hex): 以十六进制数字表示的寄存器值（例如 0x1FFA）
    • page_id (Optional, hex): （仅 RTL8201）写入前要选择的寄存器页号（例如第 7 页写作 0x07）

  • power_pin (Optional, Pin Schema): 控制 Ethernet 控制器电源/复位状态的引脚。不设置表示无电源引脚（默认）。

GENERIC（RGMII）配置变量

Section titled “GENERIC（RGMII）配置变量”

GENERIC 类型通过内部 EMAC 的 RGMII（简化千兆媒体独立接口，千兆）

接口驱动标准的 IEEE 802.3 PHY，使用 ESP-IDF 内置的通用 PHY 驱动程序。它仅在 支持千兆的型号（目前是 ESP32-S31）上受支持。RGMII 数据、控制和时钟 GPIO 取自 ESP-IDF 按目标（per-target）的默认配置，因此只需设置管理引脚：

  • mdc_pin (Required, Pin): MDC 引脚。在 ESP32-S31 上为 GPIO5。
  • mdio_pin (Required, Pin): MDIO 引脚。在 ESP32-S31 上为 GPIO6。
  • phy_addr (Optional, int): Ethernet 控制器的 PHY 地址。默认为 0。
  • power_pin (Optional, Pin): PHY 复位/电源引脚。在 ESP32-S31 上为 GPIO7。建议设置，以便 PHY 在启动时干净地复位。
  • phy_registers (Optional, mapping): Ethernet 初始化后要设置的任意 PHY 寄存器值，使用与上面 RMII 配置变量 相同的 address/value/page_id 子选项。

YT8531（RGMII）配置变量

Section titled “YT8531（RGMII）配置变量”

YT8531 类型是 GENERIC RGMII PHY 加上 Motorcomm YT8531 所需的芯片特定初始化（它是 ESP32-S31 功能核开发板上的 PHY）。硬件复位后，YT8531 会以禁用自动协商且没有 RGMII 时钟延迟的状态启动，因此 ESPHome 会自动重新启用自动协商并配置约 2 ns 的 Tx/Rx 时钟延迟，以保证可靠的千兆运行。对于基于 YT8531 的开发板，请使用此类型而不是 GENERIC；无需额外选项。

它采用与 GENERIC 类型相同的配置变量（mdc_pin、mdio_pin、phy_addr、power_pin、phy_registers）。在 ESP32-S31 上，管理引脚为 mdc_pin: GPIO5、mdio_pin: GPIO6 和 power_pin: GPIO7。

SPI 配置变量

Section titled “SPI 配置变量”

  • clk_pin (Required, Pin): SPI 时钟引脚。

  • mosi_pin (Required, Pin): SPI MOSI 引脚。

  • miso_pin (Required, Pin): SPI MISO 引脚。

  • cs_pin (Required, Pin): SPI 片选引脚。

  • interrupt_pin (Optional, Pin): 中断引脚。 此变量在较旧的框架中是必需的。参见下文。

  • reset_pin (Optional, Pin): 复位引脚。

  • clock_speed (Optional, float): SPI 时钟速度。仅限 ESP32。 允许 8MHz 到 80MHz 之间的任何频率，但会使用 80MHz 的最近整数分频， 即当配置 15MHz 时使用 16MHz（80MHz / 5）。 默认：26.67MHz。

  • polling_interval (Optional, Time): 如果未设置 interrupt_pin， 请设置周期性轮询的时间间隔。最小值为 1ms；默认为 10ms。仅限 ESP32。 较旧的框架可能不支持此变量。有关详细信息参见下文。

  • interface (Optional, string): 控制应使用哪个 ESP-IDF SPI 实现。 值可以是 spi2 或 spi3。

在 ESP32 上，interrupt_pin 和 polling_interval 选项控制 SPI Ethernet 芯片的轮询方式。在 RP2040 上，arduino-pico 框架会自动处理数据包处理。

ESP32 SPI 轮询模式详细信息：

SPI 轮询模式（无中断引脚）的支持由 ESP-IDF 5.1.4+ 提供。

当使用支持 SPI 轮询模式的框架构建时，可以设置 interrupt_pin 或 polling_interval 之一。如果两者都设置，ESPHome 将报错。

如果你使用的是不支持 SPI 轮询模式的框架，则 interrupt_pin 是必需的，并且你不能设置 polling_interval。

高级通用配置变量

Section titled “高级通用配置变量”

  • manual_ip (Optional): 手动配置节点的静态 IP。

    • static_ip (Required, IPv4 address): 节点的静态 IP。
    • gateway (Required, IPv4 address): 本地网络的网关。
    • subnet (Required, IPv4 address): 本地网络的子网掩码。
    • dns1 (Optional, IPv4 address): 要使用的主 DNS 服务器。
    • dns2 (Optional, IPv4 address): 要使用的备用 DNS 服务器。

  • use_address (Optional, string): 手动覆盖用于连接 ESP 的地址。默认为自动生成的值。例如，如果你更改了静态 IP，并想通过 OTA 刷写到之前配置的 IP 地址。

  • domain (Optional, string): 设置用于上传的节点主机名的域。 例如，如果设置为 .local，所有上传都将发送到 <HOSTNAME>.local。 默认为 .local。

  • mac_address (Optional, MAC Address): 设置 Ethernet 接口的 MAC 地址。

  • enable_on_boot (Optional, boolean): 如果启用，Ethernet 接口将在启动时启用。默认为 true。

  • on_connect (Optional, Automation): 建立连接时执行的操作。

  • on_disconnect (Optional, Automation): 连接断开时执行的操作。

  • id (Optional, ID): 手动指定用于代码生成的 ID。

NOTE

如果你的 Ethernet 开发板并非内置微控制器，通常人们会尝试使用飞线、杜邦线等连接 Ethernet 控制器。然而，这种方法很可能失败，因为 Ethernet 接口使用高频时钟信号，无法可靠地通过这些类型的连接传输。

NOTE

基于 SPI 的芯片不使用 Spi。这意味着 SPI 引脚不能与其他设备共享。

配置示例

Section titled “配置示例”

Olimex ESP32-POE:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO17
    mode: CLK_OUT
  phy_addr: 0
  power_pin: GPIO12

NOTE

Olimex POE 卡的 WROVER 版本将 CLK 更改为引脚 GPIO0。

Olimex ESP32-EVB:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 0

Olimex ESP32-GATEWAY and LILYGO TTGO T-Internet-POE ESP32-WROOM LAN8270A:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO17
    mode: CLK_OUT
  phy_addr: 0

LILYGO TTGO T-Internet ESP32-WROVER-E LAN8270:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_OUT
  phy_addr: 0
  power_pin: GPIO04

Wireless Tag WT32-ETH01 and SMLIGHT SLZB-06 PoE Zigbee:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 1
  power_pin: GPIO16

M5Stack PoESP32 and ESP32-Ethernet-Kit:

ethernet:
  type: IP101
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 1
  power_pin: GPIO5

DFRobot Edge101 and ESP32-DOWD-V3:

ethernet:
  type: IP101
  mdc_pin: GPIO4
  mdio_pin: GPIO13
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  power_pin: GPIO2
  phy_addr: 1

AiThinker ESP32-G Gateway:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO17
    mode: CLK_OUT
  phy_addr: 1
  power_pin: GPIO5

Silicognition wESP32：

# for board up to rev.5
ethernet:
  type: LAN8720
  mdc_pin: GPIO16
  mdio_pin: GPIO17
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 0


# for board rev.7 and up
ethernet:
  type: RTL8201
  mdc_pin: GPIO16
  mdio_pin: GPIO17
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 0
  phy_registers:
    - address: 0x10
      value: 0x1FFA
      page_id: 0x07

NOTE

修订版 5 及以下的 wESP32 开发板使用 LAN8720 Ethernet PHY。修订版 7 及以上的使用 RTL8201 Ethernet PHY。

Silicognition ManT1S:

ethernet:
  type: LAN8670
  mdc_pin:
    number: GPIO8
    ignore_pin_validation_error: true
  mdio_pin:
    number: GPIO7
    ignore_pin_validation_error: true
  clk:
    pin:
      number: GPIO0
      ignore_strapping_warning: true
    mode: CLK_EXT_IN
  phy_addr: 0

NOTE

MDC 和 MDIO 引脚需要 ignore_pin_validation_error 选项，因为引脚验证器假定这些引脚用于闪存。然而，此开发板使用 ESP32-PICO-V3-02 模组，该模组将这些引脚留作他用，因此需要禁用此检查。

OpenHacks LAN8720:

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  phy_addr: 1

NOTE

此开发板存在一个可能导致 ESP32 以程序模式启动的问题。测试时，请确保你正在监视串口输出，并多次重启设备，以查看它是否能够正确启动到程序中。

Esp32-Stick-Eth、Esp32-Stick-PoE-P 和 Esp32-Stick-PoE-A：

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO17
    mode: CLK_OUT
  phy_addr: 1

LILYGO T-ETH-Lite ESP32:

ethernet:
  type: RTL8201
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 0
  power_pin: GPIO12

QEMU qemu-system-xtensa:

ethernet:
  type: OPENETH

Waveshare ESP32-S3-ETH PoE:

ethernet:
  type: W5500
  clk_pin: GPIO13
  mosi_pin: GPIO11
  miso_pin: GPIO12
  cs_pin: GPIO14
  interrupt_pin: GPIO10
  reset_pin: GPIO9

ETH01-Evo:

ethernet:
  type: DM9051
  clk_pin: GPIO07
  mosi_pin: GPIO10
  miso_pin: GPIO03
  cs_pin: GPIO09
  interrupt_pin: GPIO08
  reset_pin: GPIO06
  clock_speed: 8MHz

NOTE

使用更高的 clock_speed（包括默认值）可能会导致接收错误和数据包丢失。

ENC28J60（ESP32，SPI）：

ethernet:
  type: ENC28J60
  clk_pin: GPIOXX
  mosi_pin: GPIOXX
  miso_pin: GPIOXX
  cs_pin: GPIOXX
  interrupt_pin: GPIOXX
  reset_pin: GPIOXX
  clock_speed: 10MHz

NOTE

ENC28J60 是一个 10Mbps 的 Ethernet 控制器。要获得更高的吞吐量，请考虑改用 W5500（100Mbps）。

ENC28J60（RP2040 Pico，SPI）：

ethernet:
  type: ENC28J60
  clk_pin: 18
  mosi_pin: 19
  miso_pin: 16
  cs_pin: 17
  interrupt_pin: 21
  reset_pin: 20

WIZnet W5500-EVB-Pico (RP2040):

rp2040:
  board: wiznet_5500_evb_pico


ethernet:
  type: W5500
  clk_pin: 18
  mosi_pin: 19
  miso_pin: 16
  cs_pin: 17
  interrupt_pin: 21
  reset_pin: 20

WIZnet W5100S-EVB-Pico (RP2040):

rp2040:
  board: wiznet_5100s_evb_pico


ethernet:
  type: W5100
  clk_pin: 18
  mosi_pin: 19
  miso_pin: 16
  cs_pin: 17
  interrupt_pin: 21
  reset_pin: 20

WIZnet W6300-EVB-Pico2 (RP2350):

rp2040:
  board: wiznet_6300_evb_pico2


ethernet:
  type: W6300
  clk_pin: 17
  mosi_pin: 18
  miso_pin: 19
  cs_pin: 16
  interrupt_pin: 15
  reset_pin: 22

NOTE

W6300 使用硬编码引脚的 PIO QSPI——它不使用 Arduino SPI。此开发板的 YAML 模式仍然要求填写 clk_pin、mosi_pin、miso_pin 和 cs_pin 字段，但它们不能用于引脚重映射的用户配置；它们必须设置为如上所示的开发板固定 QSPI 引脚布局。上游 arduino-pico 驱动程序的一个问题会导致 GPIO 0（UART TX）在初始化期间被复位，这会干扰 UART 串口日志。设备运行和 OTA 不受影响。

WIZnet W6100-EVB-Pico (RP2040):

rp2040:
  board: wiznet_6100_evb_pico


ethernet:
  type: W6100
  clk_pin: 18
  mosi_pin: 19
  miso_pin: 16
  cs_pin: 17
  interrupt_pin: 21
  reset_pin: 20

on_connect/on_disconnect 触发器

Section titled “on_connect/on_disconnect 触发器”

当 Ethernet 连接建立或断开时会触发此触发器。

ethernet:
  # ...
  on_connect:
    - switch.turn_on: switch1
  on_disconnect:
    - switch.turn_off: switch1

操作

Section titled “操作”

ethernet.disable 操作

Section titled “ethernet.disable 操作”

此操作按需关闭 Ethernet 接口。

on_...:
  then:
    - ethernet.disable:

NOTE

如果禁用没有配置其他网络接口的设备上的 Ethernet，请注意为 API 组件设置的重新连接超时。如果 Ethernet 关闭的时间超过该超时时间，设备将重新启动！

ethernet.enable 操作

Section titled “ethernet.enable 操作”

此操作按需打开 Ethernet 接口。

on_...:
  then:
    - ethernet.enable:

NOTE

如果你不希望 Ethernet 在启动时启用，可以将配置选项 enable_on_boot 设置为 false。

条件

Section titled “条件”

ethernet.connected 条件

Section titled “ethernet.connected 条件”

此条件检查设备当前是否具有 Ethernet 连接。

on_...:
  if:
    condition:
      ethernet.connected:
    then:
      - logger.log: Ethernet is connected!

其对应的 lambda 写法是 id(ethernet_id).is_connected()。

ethernet.enabled 条件

Section titled “ethernet.enabled 条件”

此条件检查 Ethernet 接口当前是否处于启用状态。

on_...:
  if:
    condition:
      ethernet.enabled:
    then:
      - logger.log: Ethernet is enabled!

其对应的 lambda 写法是 id(ethernet_id).is_enabled()。

另请参见

Section titled “另请参见”