Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

The ethernet: component provides wired network connectivity for ESP32 and RP2040/RP2350 boards. For ESP32, both RMII PHY chips (LAN8720, RTL8201, IP101, and others) connected to the built-in Ethernet MAC, and SPI-based controllers (W5500, DM9051, ENC28J60) are supported. For RP2040/RP2350, only SPI/PIO controllers are supported (W5100, W5500, W6100, W6300, ENC28J60). Wired Ethernet and Wi-Fi cannot be used simultaneously, even when both are physically present on a board.

​
Minimal Examples

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

​
Supported Chipsets

TypeInterfacePlatforms
LAN8720RMIIESP32 only
LAN8670RMIIESP32 only
RTL8201RMIIESP32 only
DP83848RMIIESP32 only
IP101RMIIESP32 only
JL1101RMIIESP32 only
KSZ8081RMIIESP32 only
KSZ8081RNARMIIESP32 only
OPENETHQEMUESP32 only
W5500SPIESP32 + RP2040
DM9051SPIESP32 only
ENC28J60SPI (10 Mbps)ESP32 + RP2040
W5100SPIRP2040 only
W6100SPIRP2040/RP2350 only
W6300PIO QSPIRP2040/RP2350 only

​
RMII Configuration Variables

​
type
string
required
PHY chipset type. See the supported chipsets table above.
​
mdc_pin
pin
required
Management Data Clock pin. Typically GPIO23 on ESP32 boards with built-in PHY.
​
mdio_pin
pin
required
Management Data I/O pin. Typically GPIO18 on ESP32 boards with built-in PHY.
​
clk
mapping
required
RMII clock configuration.
  • pin (Required, pin): The clock GPIO pin.
  • mode (Required, string): Clock source. CLK_EXT_IN uses an external crystal oscillator on the PHY board; CLK_OUT uses the ESP32’s internal oscillator.
​
phy_addr
int
PHY chip address on the MDIO bus. Defaults to 0. Check your board’s schematic.
​
power_pin
pin
GPIO pin controlling the PHY’s power or reset line. Leave unset if your board has no power control pin.
​
phy_registers
list
Arbitrary PHY register values to write after Ethernet initialization. Each entry requires address (hex) and value (hex), and optionally page_id (hex, RTL8201 only).

​
SPI Configuration Variables

​
clk_pin
pin
required
SPI clock pin.
​
mosi_pin
pin
required
SPI MOSI (controller-out, peripheral-in) pin.
​
miso_pin
pin
required
SPI MISO (controller-in, peripheral-out) pin.
​
cs_pin
pin
required
SPI chip select pin.
​
interrupt_pin
pin
Interrupt pin for packet-ready notification. Required for older ESP-IDF frameworks. Optional on ESP-IDF 5.1.4+ (use polling_interval instead).
​
reset_pin
pin
GPIO pin wired to the controller’s reset line. Optional but recommended.
​
clock_speed
float
ESP32 only. SPI bus clock speed. Any frequency 8–80 MHz is accepted; the nearest integer divisor of 80 MHz is used. Defaults to 26.67MHz (80 MHz ÷ 3).
​
polling_interval
Time
ESP32 only. Polling interval when no interrupt_pin is configured. Requires ESP-IDF 5.1.4+. Minimum 1ms. Defaults to 10ms. Cannot be set simultaneously with interrupt_pin.
​
interface
string
ESP32 only. Which SPI peripheral to use: spi2 or spi3.

​
Common Configuration Variables

​
manual_ip
mapping
Configure a static IP address. Recommended for reliable OTA and fast reconnection.
  • static_ip (Required, IPv4): Static IP address.
  • gateway (Required, IPv4): Default gateway (router IP).
  • subnet (Required, IPv4): Subnet mask (e.g. 255.255.255.0).
  • dns1 (Optional, IPv4): Primary DNS server.
  • dns2 (Optional, IPv4): Secondary DNS server.
​
use_address
string
Override the target address for OTA uploads. Useful when migrating between IPs.
​
domain
string
mDNS domain suffix. Defaults to .local.
​
mac_address
MAC Address
Override the Ethernet interface MAC address.
​
on_connect
Automation
Triggered when a wired network link is established.
​
on_disconnect
Automation
Triggered when the wired network link is lost.

​
Board-Specific Examples

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

​
Complete Example with Static IP and Automations

esphome:
  name: eth-controller
  friendly_name: "Wired Ethernet Controller"

esp32:
  variant: esp32
  framework:
    type: esp-idf

ethernet:
  type: LAN8720
  mdc_pin: GPIO23
  mdio_pin: GPIO18
  clk:
    pin: GPIO17
    mode: CLK_OUT
  phy_addr: 0
  power_pin: GPIO12
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1
  on_connect:
    - logger.log: "Ethernet link up"
  on_disconnect:
    - logger.log: "Ethernet link down"

logger:
api:
  encryption:
    key: !secret api_key
ota:
  - platform: esphome
    password: !secret ota_password
SPI-based Ethernet chips do not use the ESPHome SPI bus component. Their SPI pins cannot be shared with other SPI devices. Wire each Ethernet controller to dedicated GPIO pins.
Avoid using flying leads or Dupont wires for RMII Ethernet connections. The RMII clock signal runs at 50 MHz and will not reliably propagate over loose wires, causing intermittent connection failures. Use proper PCB traces or a purpose-built carrier board.
The ENC28J60 is limited to 10 Mbps. For applications requiring higher throughput, use a W5500 (100 Mbps) instead.
The CLK_EXT_IN clock mode requires an external 50 MHz oscillator on the PHY board. The CLK_OUT mode uses the ESP32’s internal PLL — more common on boards where the ESP32 supplies the clock to the PHY. Check your board’s schematic to determine which mode is correct.

Build docs developers (and LLMs) love

Get started for freeTalk to us