Skip to content
ESPHome - Smart Home Made Simple 2026.6.4

Ethernet Component

This ESPHome component enables wired Ethernet connections for ESP32 and RP2040 boards.

  • ESP32: Supports RMII PHY chips (LAN8720, RTL8201, etc.) and SPI Ethernet chips (W5500, DM9051, ENC28J60).
  • RP2040/RP2350: Supports SPI/PIO Ethernet chips (W5100, W5500, W6100, W6300, ENC28J60).

This component and the Wi-Fi component may not be used simultaneously, even if both are physically available.

# 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

Configuration variables

Section titled “Configuration variables”

  • type (Required, string): The type of LAN chipset/phy.

    Supported chipsets are:

    • 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 configuration variables

Section titled “RMII configuration variables”

  • mdc_pin (Required, Pin): The MDC pin of the board. Usually this is GPIO23.

  • mdio_pin (Required, Pin): The MDIO pin of the board. Usually this is GPIO18.

  • clk (Required, mapping):

    • pin (Required, Pin): The RMII clock pin.

    • mode (Required, string): The clock mode of the data lines. See your board's datasheet for more details. Must be one of the following values:

      • CLK_EXT_IN - External clock
      • CLK_OUT - Internal clock

  • phy_addr (Optional, int): The PHY addr type of the Ethernet controller. Defaults to 0.

  • phy_registers (Optional, mapping): Arbitrary PHY register values to set after Ethernet initialization.

    • address (Required, hex): The register address as a hex number (e.g. 0x10 for address 16)
    • value (Required, hex): The value of the register to set as a hex number (e.g. 0x1FFA )
    • page_id (Optional, hex): (RTL8201 only) Register page number to select before writing (e.g. 0x07 for page 7)

  • power_pin (Optional, Pin Schema): The pin controlling the power/reset status of the Ethernet controller. Leave unspecified for no power pin (default).

GENERIC (RGMII) configuration variables

Section titled “GENERIC (RGMII) configuration variables”

The GENERIC type drives a standard IEEE 802.3 PHY over the internal EMAC's RGMII (Reduced Gigabit Media-Independent Interface, gigabit) interface, using ESP-IDF's built-in generic PHY driver. It is only supported on gigabit-capable variants (currently the ESP32-S31). The RGMII data, control and clock GPIOs are taken from the ESP-IDF per-target default configuration, so only the management pins need to be set:

  • mdc_pin (Required, Pin): The MDC pin. On the ESP32-S31 this is GPIO5.
  • mdio_pin (Required, Pin): The MDIO pin. On the ESP32-S31 this is GPIO6.
  • phy_addr (Optional, int): The PHY address of the Ethernet controller. Defaults to 0.
  • power_pin (Optional, Pin): The PHY reset/power pin. On the ESP32-S31 this is GPIO7. Recommended so the PHY is reset cleanly at startup.
  • phy_registers (Optional, mapping): Arbitrary PHY register values to set after Ethernet initialization, with the same address/value/page_id sub-options as the RMII configuration variables above.

YT8531 (RGMII) configuration variables

Section titled “YT8531 (RGMII) configuration variables”

The YT8531 type is the GENERIC RGMII PHY plus the chip-specific initialization the Motorcomm YT8531 requires (it is the PHY on the ESP32-S31 Functional-Core Board). On a hardware reset the YT8531 comes up with auto-negotiation disabled and without RGMII clock delays, so ESPHome automatically re-enables auto-negotiation and configures the ~2 ns Tx/Rx clock delays needed for reliable gigabit operation. Use this type instead of GENERIC for YT8531-based boards; no extra options are needed.

It takes the same configuration variables as the GENERIC type (mdc_pin, mdio_pin, phy_addr, power_pin, phy_registers). On the ESP32-S31 the management pins are mdc_pin: GPIO5, mdio_pin: GPIO6 and power_pin: GPIO7.

SPI configuration variables

Section titled “SPI configuration variables”

  • clk_pin (Required, Pin): The SPI clock pin.

  • mosi_pin (Required, Pin): The SPI MOSI pin.

  • miso_pin (Required, Pin): The SPI MISO pin.

  • cs_pin (Required, Pin): The SPI chip select pin.

  • interrupt_pin (Optional, Pin): The interrupt pin. This variable is required for older frameworks. See below.

  • reset_pin (Optional, Pin): The reset pin.

  • clock_speed (Optional, float): The SPI clock speed. ESP32 only. Any frequency between 8MHz and 80MHz is allowed, but the nearest integer division of 80MHz is used, i.e. 16MHz (80MHz / 5) is used when 15MHz is configured. Default: 26.67MHz.

  • polling_interval (Optional, Time): If interrupt_pin is not set, set the time interval for periodic polling. Minimum is 1ms; defaults to 10ms. ESP32 only. Older frameworks may not support this variable. See below for details.

  • interface (Optional, string): Controls which ESP-IDF SPI implementation should be used. Value may be either spi2 or spi3.

On ESP32, the interrupt_pin and polling_interval options control how the SPI Ethernet chip is polled. On RP2040, the arduino-pico framework handles packet processing automatically.

ESP32 SPI polling mode details:

Support for SPI polling mode (no interrupt pin) is provided by ESP-IDF 5.1.4+.

When building with frameworks that support SPI polling mode, either interrupt_pin or polling_interval can be set. If you set both, ESPHome will throw an error.

If you are using a framework that does not support SPI polling mode, interrupt_pin is required and you cannot set polling_interval.

Advanced common configuration variables

Section titled “Advanced common configuration variables”

  • manual_ip (Optional): Manually configure the static IP of the node.

    • static_ip (Required, IPv4 address): The static IP of your node.
    • gateway (Required, IPv4 address): The gateway of the local network.
    • subnet (Required, IPv4 address): The subnet of the local network.
    • dns1 (Optional, IPv4 address): The main DNS server to use.
    • dns2 (Optional, IPv4 address): The backup DNS server to use.

  • use_address (Optional, string): Manually override what address to use to connect to the ESP. Defaults to auto-generated value. For example, if you have changed your static IP and want to flash OTA to the previously configured IP address.

  • domain (Optional, string): Set the domain of the node hostname used for uploading. For example, if it's set to .local, all uploads will be sent to <HOSTNAME>.local. Defaults to .local.

  • mac_address (Optional, MAC Address): Set the MAC address of the ethernet interface.

  • enable_on_boot (Optional, boolean): If enabled, the Ethernet interface will be enabled on boot. Defaults to true.

  • on_connect (Optional, Automation): An action to be performed when a connection is established.

  • on_disconnect (Optional, Automation): An action to be performed when the connection is dropped.

  • id (Optional, ID): Manually specify the ID used for code generation.

NOTE

If your Ethernet board is not designed with the microcontroller built in, it's common to attempt to use flying leads, dupont wires, etc. to connect the Ethernet controller. This approach is likely to fail, however, as the Ethernet interface uses a high frequency clock signal that will not travel reliably over these types of connections.

NOTE

SPI based chips do not use Spi. This means that SPI pins can't be shared with other devices.

Configuration examples

Section titled “Configuration examples”

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

WROVER version of Olimex POE cards change CLK to pin 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

Revision 5 and below of the wESP32 board use the LAN8720 Ethernet PHY. Revision 7 and newer of it use the 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

The ignore_pin_validation_error options are required for the MDC and MDIO pins, since the pin validator assumes these pins are used for flash. However, this board uses the ESP32-PICO-V3-02 module, which has these pins available for other uses, so this check needs to be disabled.

OpenHacks LAN8720:

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

NOTE

This board has an issue that might cause the ESP32 to boot in program mode. When testing, make sure you are monitoring the serial output and reboot the device several times to see if it boots into the program properly.

Esp32-Stick-Eth and Esp32-Stick-PoE-P and 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

Using a higher clock_speed, including default, might cause rx errors and dropped packets.

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

The ENC28J60 is a 10Mbps Ethernet controller. For higher throughput, consider using a W5500 (100Mbps) instead.

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

The W6300 uses PIO QSPI with hardcoded pins — it does not use Arduino SPI. The clk_pin, mosi_pin, miso_pin, and cs_pin fields are still required by the YAML schema for this board, but they are not user-configurable for pin remapping; they must be set to the board's fixed QSPI pinout as shown above. An upstream arduino-pico driver issue causes GPIO 0 (UART TX) to be reset during initialization, which disrupts UART serial logging. Device operation and OTA are unaffected.

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 Trigger

Section titled “on_connect / on_disconnect Trigger”

This trigger is activated when an Ethernet connection is established or dropped.

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

Actions

Section titled “Actions”

ethernet.disable Action

Section titled “ethernet.disable Action”

This action turns off the Ethernet interface on demand.

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

NOTE

Be mindful of the reboot timeout set for the API component if you disable Ethernet on a device that has no other network interface configured. If Ethernet remains off for longer than that timeout, the device will reboot!

ethernet.enable Action

Section titled “ethernet.enable Action”

This action turns on the Ethernet interface on demand.

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

NOTE

The configuration option enable_on_boot can be set to false if you do not want Ethernet to be enabled on boot.

Conditions

Section titled “Conditions”

ethernet.connected Condition

Section titled “ethernet.connected Condition”

This Condition checks if the device currently has an Ethernet connection.

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

The lambda equivalent for this is id(ethernet_id).is_connected().

ethernet.enabled Condition

Section titled “ethernet.enabled Condition”

This Condition checks if the Ethernet interface is currently enabled.

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

The lambda equivalent for this is id(ethernet_id).is_enabled().

See Also

Section titled “See Also”