ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
ethernet_component.h
Go to the documentation of this file.
1#pragma once
2
5#include "esphome/core/hal.h"
9
10#include <atomic>
11
12#ifdef USE_ETHERNET
13
14#ifdef USE_ESP32
15#include "esp_eth.h"
16#ifdef USE_ETHERNET_SPI
17#include "hal/spi_types.h"
18#ifdef USE_SPI
20#endif
21#endif
22#include "esp_eth_mac.h"
23#include "esp_eth_mac_esp.h"
24#include "esp_netif.h"
25#include "esp_mac.h"
26#include "esp_idf_version.h"
27
28#if CONFIG_ETH_USE_ESP32_EMAC
29extern "C" eth_esp32_emac_config_t eth_esp32_emac_default_config(void);
30#endif
31#endif // USE_ESP32
32
33#ifdef USE_RP2
34#if defined(USE_ETHERNET_W5500)
35#include <W5500lwIP.h>
36#elif defined(USE_ETHERNET_W5100)
37#include <W5100lwIP.h>
38#elif defined(USE_ETHERNET_W6100)
39#include <W6100lwIP.h>
40#elif defined(USE_ETHERNET_W6300)
41#include <W6300lwIP.h>
42// W6300 uses PIO QSPI, not Arduino SPI. The upstream Wiznet6300 class
43// incorrectly returns needsSPI()=true, causing LwipIntfDev::begin() to
44// call SPI.begin() which claims GPIOs that PIO QSPI needs.
45// This wrapper hides needsSPI() with a version returning false.
46class Wiznet6300NoSPI : public Wiznet6300 {
47 public:
48 using Wiznet6300::Wiznet6300;
49 constexpr bool needsSPI() const { return false; }
50};
51using Wiznet6300lwIPFixed = LwipIntfDev<Wiznet6300NoSPI>;
52#elif defined(USE_ETHERNET_ENC28J60)
53#include <ENC28J60lwIP.h>
54#else
55#error "Unsupported RP2040 SPI Ethernet type"
56#endif
57#endif
58
59namespace esphome::ethernet {
60
61#ifdef USE_ETHERNET_IP_STATE_LISTENERS
71 public:
72 virtual void on_ip_state(const network::IPAddresses &ips, const network::IPAddress &dns1,
73 const network::IPAddress &dns2) = 0;
74};
75#endif // USE_ETHERNET_IP_STATE_LISTENERS
76
99
107
108#ifdef USE_ETHERNET_MANUAL_IP
111static constexpr size_t ETHERNET_MANUAL_IP_SIZE = 5 * 4;
112extern const uint8_t ETHERNET_MANUAL_IP[ETHERNET_MANUAL_IP_SIZE] PROGMEM;
114#endif
115
121
122enum class EthernetComponentState : uint8_t {
123 STOPPED,
125 CONNECTED,
126};
127
128// Platform-neutral duplex/speed types
129#ifndef USE_ESP32
130// NOLINTBEGIN(readability-identifier-naming)
133// NOLINTEND(readability-identifier-naming)
134#endif
135
136class EthernetComponent final : public Component {
137 public:
139 void setup() override;
140 void loop() override;
141 void dump_config() override;
142 float get_setup_priority() const override { return setup_priority::ETHERNET; }
143 void on_powerdown() override { powerdown(); }
145
146 // Per-interface lifecycle (parallels WiFiComponent::enable/disable/is_disabled).
147 // enable_on_boot defaults to true; when false, setup() runs all the driver/netif
148 // installation but skips esp_eth_start(), keeping the link cold until enable() is
149 // called. This is the primary lever for memory reclamation in multi-interface
150 // configurations where only one interface should carry traffic at a time.
151 void set_enable_on_boot(bool enable_on_boot) { this->enable_on_boot_ = enable_on_boot; }
152 void enable();
153 void disable();
154 bool is_disabled() { return this->disabled_; }
155 bool is_enabled() { return !this->disabled_; }
156
157#ifdef USE_ESP32
161#endif
162
164 void set_fixed_mac(const std::array<uint8_t, MAC_ADDRESS_SIZE> &mac) { this->fixed_mac_ = mac; }
165
170 const char *get_use_address() const { return this->use_address_; }
171 void set_use_address(const char *use_address) { this->use_address_ = use_address; }
172 void get_eth_mac_address_raw(uint8_t *mac);
173 const char *get_eth_mac_address_pretty_into_buffer(std::span<char, MAC_ADDRESS_PRETTY_BUFFER_SIZE> buf);
176 bool powerdown();
177
178#ifdef USE_ESP32
179 esp_eth_handle_t get_eth_handle() const { return this->eth_handle_; }
180
181#ifdef USE_ETHERNET_SPI
182 void set_clk_pin(uint8_t clk_pin) { this->clk_pin_ = clk_pin; }
183 void set_miso_pin(uint8_t miso_pin) { this->miso_pin_ = miso_pin; }
184 void set_mosi_pin(uint8_t mosi_pin) { this->mosi_pin_ = mosi_pin; }
185 void set_cs_pin(uint8_t cs_pin) { this->cs_pin_ = cs_pin; }
186 void set_interrupt_pin(uint8_t interrupt_pin) { this->interrupt_pin_ = interrupt_pin; }
187 void set_reset_pin(uint8_t reset_pin) { this->reset_pin_ = reset_pin; }
188 void set_clock_speed(int clock_speed) { this->clock_speed_ = clock_speed; }
189 void set_interface(spi_host_device_t interface) { this->interface_ = interface; }
190#ifdef USE_SPI
191 void set_spi_parent(spi::SPIComponent *parent) { this->spi_parent_ = parent; }
192#endif
193#ifdef USE_ETHERNET_SPI_POLLING_SUPPORT
194 void set_polling_interval(uint32_t polling_interval) { this->polling_interval_ = polling_interval; }
195#endif
196#else
197 void set_phy_addr(uint8_t phy_addr) { this->phy_addr_ = phy_addr; }
198 void set_power_pin(int power_pin) { this->power_pin_ = power_pin; }
199 void set_mdc_pin(uint8_t mdc_pin) { this->mdc_pin_ = mdc_pin; }
200 void set_mdio_pin(uint8_t mdio_pin) { this->mdio_pin_ = mdio_pin; }
201 void set_clk_pin(uint8_t clk_pin) { this->clk_pin_ = clk_pin; }
202 void set_clk_mode(emac_rmii_clock_mode_t clk_mode) { this->clk_mode_ = clk_mode; }
203#ifdef ESPHOME_ETHERNET_PHY_REGISTER_COUNT
204 void add_phy_register(PHYRegister register_value) { this->phy_registers_.push_back(register_value); }
205#endif
206#endif // USE_ETHERNET_SPI
207#endif // USE_ESP32
208
209#ifdef USE_RP2
210 void set_clk_pin(uint8_t clk_pin) { this->clk_pin_ = clk_pin; }
211 void set_miso_pin(uint8_t miso_pin) { this->miso_pin_ = miso_pin; }
212 void set_mosi_pin(uint8_t mosi_pin) { this->mosi_pin_ = mosi_pin; }
213 void set_cs_pin(uint8_t cs_pin) { this->cs_pin_ = cs_pin; }
214 void set_interrupt_pin(int8_t interrupt_pin) { this->interrupt_pin_ = interrupt_pin; }
215 void set_reset_pin(int8_t reset_pin) { this->reset_pin_ = reset_pin; }
216#endif // USE_RP2
217
218#ifdef USE_ETHERNET_IP_STATE_LISTENERS
219 void add_ip_state_listener(EthernetIPStateListener *listener) { this->ip_state_listeners_.push_back(listener); }
220#endif
221
222#ifdef USE_ETHERNET_CONNECT_TRIGGER
224#endif
225#ifdef USE_ETHERNET_DISCONNECT_TRIGGER
227#endif
228
229 protected:
230 void start_connect_();
231 void finish_connect_();
232#if LWIP_IPV6
233 esp_err_t ensure_ip6_linklocal_();
234#endif
236
237#ifdef USE_ESP32
238 // ESP-IDF only: defers the SPI bus init, netif creation, MAC/PHY install, driver
239 // install, netif attach, and event handler registration (which together allocate
240 // ~3-8KB of DMA-capable internal SRAM via SPI driver state + eth driver RX queue)
241 // until ethernet actually needs to come up. Idempotent — guarded by the
242 // ethernet_initialized_ flag. Called from setup() when enable_on_boot_=true, or
243 // from enable() on first runtime enable. Mirrors wifi_lazy_init_() in WiFi.
244 void ethernet_lazy_init_();
245#endif
246
247#ifdef USE_ETHERNET_IP_STATE_LISTENERS
249#endif
250
251#ifdef USE_ESP32
252 static void eth_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data);
253 static void got_ip_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data);
254#if LWIP_IPV6
255 static void got_ip6_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data);
256#endif /* LWIP_IPV6 */
257 void log_error_and_mark_failed_(esp_err_t err, const char *message);
258#ifdef USE_ETHERNET_KSZ8081
260 void ksz8081_set_clock_reference_(esp_eth_mac_t *mac);
261#endif
262#ifdef USE_ETHERNET_YT8531
265 void yt8531_phy_init_();
266#endif
267#ifdef ESPHOME_ETHERNET_PHY_REGISTER_COUNT
269 void write_phy_register_(esp_eth_mac_t *mac, PHYRegister register_data);
270#endif
271
272#ifdef USE_ETHERNET_SPI
273 uint8_t clk_pin_;
274 uint8_t miso_pin_;
275 uint8_t mosi_pin_;
276 uint8_t cs_pin_;
278 int reset_pin_{-1};
281 spi_host_device_t interface_{SPI2_HOST}; // Must match DEFAULT_SPI_INTERFACE in __init__.py
282#ifdef USE_SPI
283 // When set, the SPI bus is owned and initialized by this spi component
284 // and the ethernet chip only adds a device to it.
286#endif
287#ifdef USE_ETHERNET_SPI_POLLING_SUPPORT
289#endif
290#else
291 // Group all 32-bit members first
292 int power_pin_{-1};
293 emac_rmii_clock_mode_t clk_mode_{EMAC_CLK_EXT_IN}; // Must match DEFAULT_CLK_MODE in __init__.py
294#ifdef ESPHOME_ETHERNET_PHY_REGISTER_COUNT
296#endif
297
298 // Group all 8-bit members together
299 uint8_t clk_pin_{0}; // Must match DEFAULT_CLK_PIN in __init__.py
300 uint8_t phy_addr_{0}; // Must match DEFAULT_PHY_ADDR in __init__.py
301 uint8_t mdc_pin_{23}; // Must match DEFAULT_MDC_PIN in __init__.py
302 uint8_t mdio_pin_{18}; // Must match DEFAULT_MDIO_PIN in __init__.py
303#endif // USE_ETHERNET_SPI
304
305 // ESP32 pointers
307 esp_eth_handle_t eth_handle_;
308 esp_eth_phy_t *phy_{nullptr};
309#endif // USE_ESP32
310
311#ifdef USE_RP2
312 static constexpr uint32_t LINK_CHECK_INTERVAL = 500; // ms between link/IP polls
313#if defined(USE_ETHERNET_W5100)
314 static constexpr uint32_t RESET_DELAY_MS = 150; // W5100S PLL lock time
315#elif defined(USE_ETHERNET_W6300)
316 static constexpr uint32_t RESET_DELAY_MS = 100; // W6300 needs 100ms after hardware reset
317#else
318 static constexpr uint32_t RESET_DELAY_MS = 10;
319#endif
320#if defined(USE_ETHERNET_W5500)
321 Wiznet5500lwIP *eth_{nullptr};
322#elif defined(USE_ETHERNET_W5100)
323 Wiznet5100lwIP *eth_{nullptr};
324#elif defined(USE_ETHERNET_W6100)
325 Wiznet6100lwIP *eth_{nullptr};
326#elif defined(USE_ETHERNET_W6300)
328#elif defined(USE_ETHERNET_ENC28J60)
329 ENC28J60lwIP *eth_{nullptr};
330#else
331#error "Unsupported RP2040 SPI Ethernet type"
332#endif
334 uint8_t clk_pin_;
335 uint8_t miso_pin_;
336 uint8_t mosi_pin_;
337 uint8_t cs_pin_;
338 int8_t interrupt_pin_{-1};
339 int8_t reset_pin_{-1};
340#endif // USE_RP2
341
342 // Common members
344
345 // Group all uint8_t types together (enums and bools)
348 bool started_{false};
349 bool connected_{false};
350 bool got_ipv4_address_{false};
351 // Codegen-time YAML option. When false, setup() defers esp_eth_start().
352 bool enable_on_boot_{true};
353 // Mirror of "is the link intentionally stopped" — set when setup() honors
354 // enable_on_boot=false, cleared by enable(), set again by disable().
355 bool disabled_{false};
356#ifdef USE_ESP32
357 // Tracks whether ethernet_lazy_init_() has completed successfully. Allows enable()
358 // to be called at runtime after enable_on_boot:false without re-allocating, and
359 // ensures setup() skips the heavy init when enable_on_boot_ is false.
361#endif
362#if LWIP_IPV6
363 uint8_t ipv6_count_{0};
364 bool ipv6_setup_done_{false};
365#endif /* LWIP_IPV6 */
366
367 optional<std::array<uint8_t, MAC_ADDRESS_SIZE>> fixed_mac_;
368
369#ifdef USE_ETHERNET_IP_STATE_LISTENERS
371#ifdef USE_ESP32
372 std::atomic<uint8_t> ip_state_pending_{0};
373#endif
374#endif
375
376#ifdef USE_ETHERNET_CONNECT_TRIGGER
378#endif
379#ifdef USE_ETHERNET_DISCONNECT_TRIGGER
381#endif
382 private:
383 // Stores a pointer to a string literal (static storage duration).
384 // ONLY set from Python-generated code with string literals - never dynamic strings.
385 const char *use_address_{nullptr};
386};
387
388// NOLINTNEXTLINE(cppcoreguidelines-avoid-non-const-global-variables)
389extern EthernetComponent *global_eth_component;
390
391#ifdef USE_ESP32
392#if defined(USE_ETHERNET_JL1101) && (ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0) || \
393 ESP_IDF_VERSION < ESP_IDF_VERSION_VAL(5, 4, 2) || !defined(PLATFORMIO))
394extern "C" esp_eth_phy_t *esp_eth_phy_new_jl1101(const eth_phy_config_t *config);
395#endif
396#endif // USE_ESP32
397
398} // namespace esphome::ethernet
399
400#endif // USE_ETHERNET
constexpr bool needsSPI() const
Minimal static vector - saves memory by avoiding std::vector overhead.
Definition helpers.h:304
void set_enable_on_boot(bool enable_on_boot)
StaticVector< PHYRegister, ESPHOME_ETHERNET_PHY_REGISTER_COUNT > phy_registers_
void set_interface(spi_host_device_t interface)
static void got_ip_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
void set_polling_interval(uint32_t polling_interval)
void yt8531_phy_init_()
Apply YT8531-specific config: re-enable auto-negotiation (disabled on reset) and set the RGMII Tx/Rx ...
static constexpr uint32_t LINK_CHECK_INTERVAL
void write_phy_register_(esp_eth_mac_t *mac, PHYRegister register_data)
Set arbitratry PHY registers from config.
static void got_ip6_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
void log_error_and_mark_failed_(esp_err_t err, const char *message)
void set_spi_parent(spi::SPIComponent *parent)
esp_netif_t * get_esp_netif()
esp_netif handle, used by network for default-route arbitration.
void add_ip_state_listener(EthernetIPStateListener *listener)
void set_interrupt_pin(int8_t interrupt_pin)
network::IPAddress get_dns_address(uint8_t num)
void add_phy_register(PHYRegister register_value)
void ksz8081_set_clock_reference_(esp_eth_mac_t *mac)
Set RMII Reference Clock Select bit for KSZ8081.
StaticVector< EthernetIPStateListener *, ESPHOME_ETHERNET_IP_STATE_LISTENERS > ip_state_listeners_
void set_fixed_mac(const std::array< uint8_t, MAC_ADDRESS_SIZE > &mac)
optional< std::array< uint8_t, MAC_ADDRESS_SIZE > > fixed_mac_
void set_interrupt_pin(uint8_t interrupt_pin)
static constexpr uint32_t RESET_DELAY_MS
static void eth_event_handler(void *arg, esp_event_base_t event_base, int32_t event_id, void *event_data)
const char * get_use_address() const
Returns nullptr when no explicit use_address is configured and the address is derived at runtime from...
void set_use_address(const char *use_address)
void set_clk_mode(emac_rmii_clock_mode_t clk_mode)
const char * get_eth_mac_address_pretty_into_buffer(std::span< char, MAC_ADDRESS_PRETTY_BUFFER_SIZE > buf)
Listener interface for Ethernet IP state changes.
virtual void on_ip_state(const network::IPAddresses &ips, const network::IPAddress &dns1, const network::IPAddress &dns2)=0
const LogString * message
Definition component.cpp:35
uint8_t type
eth_esp32_emac_config_t eth_esp32_emac_default_config(void)
LwipIntfDev< Wiznet6300NoSPI > Wiznet6300lwIPFixed
const uint8_t ETHERNET_MANUAL_IP[ETHERNET_MANUAL_IP_SIZE] PROGMEM
esp_eth_phy_t * esp_eth_phy_new_jl1101(const eth_phy_config_t *config)
EthernetComponent * global_eth_component
std::array< IPAddress, 5 > IPAddresses
Definition ip_address.h:368
constexpr float ETHERNET
Definition component.h:51
struct esp_netif_obj esp_netif_t
static void uint32_t
network::IPAddress dns1
The first DNS server. 0.0.0.0 for default.
network::IPAddress dns2
The second DNS server. 0.0.0.0 for default.
uint8_t event_id
Definition tt21100.cpp:3