跳转到内容
ESPHome - 智能家居，简单易用

以太网组件

此 ESPHome 组件为 ESP32 启用有线以太网连接。

不支持 ESP8266 的以太网。

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

# RMII 芯片的示例配置项
ethernet:
  type: LAN8720
  mdc_pin: GPIOXX
  mdio_pin: GPIOXX
  clk:
    pin: GPIOXX
    mode: CLK_EXT_IN
  phy_addr: 0


  # 可选手动 IP
  manual_ip:
    static_ip: 10.0.0.42
    gateway: 10.0.0.1
    subnet: 255.255.255.0
# SPI 芯片的示例配置项
ethernet:
  type: W5500
  clk_pin: GPIOXX
  mosi_pin: GPIOXX
  miso_pin: GPIOXX
  cs_pin: GPIOXX
  interrupt_pin: GPIOXX
  reset_pin: GPIOXX

配置变量

Section titled “配置变量”

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

    支持的芯片组有：

    • LAN8720 (RMII)
    • RTL8201 (RMII)
    • DP83848 (RMII)
    • IP101 (RMII)
    • JL1101 (RMII)
    • KSZ8081 (RMII)
    • KSZ8081RNA (RMII)
    • W5500 (SPI)
    • OPENETH (QEMU, 仅限 ESP-IDF)
    • DM9051 (SPI, 仅限 ESP-IDF)
    • LAN8670 (RMII)

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): 以太网控制器的 PHY 地址类型。默认为 0。

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

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

  • power_pin (Optional, Pin Schema): 控制以太网控制器电源/复位状态的引脚。不指定则无电源引脚（默认）。

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 时钟速度。 允许 8MHz 到 80MHz 之间的任何频率，但使用 80MHz 的最接近整数除法，即配置 15MHz 时使用 16MHz（80MHz / 5）。 默认值：26.67MHz。

  • polling_interval (Optional, Time): 如果未设置 interrupt_pin， 设置定期轮询的时间间隔。最小为 1ms，默认为 10ms。 较旧的框架可能不支持此变量。详情请参阅下文。

如果您使用的是最新版本的框架，ESPHome 提供不带中断引脚的基于 SPI 的以太网模块。 以下框架支持 SPI 轮询模式（无中断引脚）：

  • ESP-IDF 5.3 或更高版本
  • ESP-IDF 5.2.1 及更高版本的 5.2.x
  • ESP-IDF 5.1.4
  • Arduino-ESP32 3.0.0 或更高版本（注意：PlatformIO 不支持这些 Arduino-ESP32 版本）

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

如果您使用的框架不支持不带中断引脚的基于 SPI 的以太网模块，则 interrupt_pin 是必需的，您不能设置 polling_interval。

高级通用配置变量

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

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

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

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

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

  • mac_address (Optional, MAC 地址): 设置以太网接口的 MAC 地址。

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

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

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

NOTE

如果您的以太网板不是设计为内置 ESP32 的，通常会尝试使用飞线、杜邦线等将以太网控制器连接到 ESP32。 这种方法可能会失败，因为以太网接口使用高频时钟信号，无法可靠地通过这些类型的连接传输。有关更多信息和接线详情，请参阅另见部分中的链接。

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 和 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 和 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 和 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 和 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:

# 适用于 rev.5 及以下的板
ethernet:
  type: LAN8720
  mdc_pin: GPIO16
  mdio_pin: GPIO17
  clk:
    pin: GPIO0
    mode: CLK_EXT_IN
  phy_addr: 0


# 适用于 rev.7 及以上的板
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

wESP32 板的修订版 5 及以下使用 LAN8720 以太网 PHY。修订版 7 及更新版本使用 RTL8201 以太网 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（包括默认值）可能会导致 rx 错误和丢包。

on_connect / on_disconnect 触发器

Section titled “on_connect / on_disconnect 触发器”

此触发器在建立或断开以太网连接时激活。

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

另见

Section titled “另见”