From 045f15c38e66f7f2599176313cafdc91efa21855 Mon Sep 17 00:00:00 2001 From: kbx81 Date: Sun, 24 May 2026 02:43:56 -0500 Subject: [PATCH] [network] Document priority list for multi-interface support Documents the new `network: priority:` list added in esphome/esphome#14255 that lets WiFi and Ethernet coexist on ESP32 family devices, and updates the ethernet and wifi component pages to remove the "may not be used simultaneously" wording. Co-Authored-By: Claude Opus 4.7 (1M context) --- src/content/docs/components/ethernet.mdx | 2 +- src/content/docs/components/network.mdx | 34 ++++++++++++++++++++++++ src/content/docs/components/wifi.mdx | 7 ++--- 3 files changed, 39 insertions(+), 4 deletions(-) diff --git a/src/content/docs/components/ethernet.mdx b/src/content/docs/components/ethernet.mdx index 74df816b6b..d6e939255c 100644 --- a/src/content/docs/components/ethernet.mdx +++ b/src/content/docs/components/ethernet.mdx @@ -10,7 +10,7 @@ This ESPHome component enables *wired* Ethernet connections for ESP32 and RP2040 - **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. +On ESP32 family devices, Ethernet may be configured alongside [WiFi](/components/wifi/) in the same configuration; see [Multi-Interface Support](/components/network/#multi-interface-support) on the [Network](/components/network/) component for how to control which interface ESPHome prefers. On RP2040, only one network interface may be configured at a time. ```yaml # Example configuration entry for RMII chips diff --git a/src/content/docs/components/network.mdx b/src/content/docs/components/network.mdx index 9cfe77ce7e..7d16c75793 100644 --- a/src/content/docs/components/network.mdx +++ b/src/content/docs/components/network.mdx @@ -19,6 +19,7 @@ network: - **enable_ipv6** (*Optional*, boolean): Enables IPv6 support. Defaults to `false`. - **min_ipv6_addr_count** (*Optional*, integer): ESPHome considers the network to be connected when it has one IPv4 address and this number of IPv6 addresses. Defaults to `0` so as to not hang on boot with networks where IPv6 is not enabled. `2` is typically a reasonable value for configurations requiring IPv6. - **enable_high_performance** (*Optional*, boolean): Explicitly enables or disables high-performance networking optimizations. Only supported on ESP32 devices. When not specified, this is automatically enabled by components that benefit from optimized network settings. Set to `false` to disable these optimizations if they cause memory issues on your device. Defaults to component-driven behavior. +- **priority** (*Optional*, list): Order in which network interfaces are brought up at boot. Each list entry names one of the supported interface types (`ethernet`, `wifi`, `openthread`, or `modem`) and may optionally specify a per-interface `timeout`. See [Multi-Interface Support](#multi-interface-support). ## High-performance networking @@ -47,6 +48,39 @@ The optimization level depends on whether PSRAM is guaranteed to be available (c > This has various security and privacy implications decribed in [RFC7721](https://datatracker.ietf.org/doc/rfc7721/), as this might leak outside of the smart home network and makes the device uniquely identifiable. > Therefore, the address generation does not comply to [RFC7217](https://datatracker.ietf.org/doc/rfc7217/). +## Multi-Interface Support + +Devices with more than one network interface — for example an ESP32 with both [WiFi](/components/wifi/) and SPI [Ethernet](/components/ethernet/) — can declare a `priority` list to control the order in which interfaces are brought up at boot and which one ESPHome prefers when more than one is connected. + +```yaml +network: + priority: + - ethernet + - wifi +``` + +In the example above, Ethernet is started first and used as the default route while it is connected; WiFi is started afterwards and is used only if Ethernet is unavailable. The first entry in the list is the most-preferred interface. + +Each entry may either be a plain interface name or a mapping with an optional per-interface `timeout`: + +```yaml +network: + priority: + - ethernet: + timeout: 30s + - wifi +``` + +The `timeout` value bounds how long ESPHome waits for that interface to come up before starting the next one in the list. It accepts the usual ESPHome [time format](/guides/configuration-types/#time) (for example `30s`, `1min`, `500ms`). A plain integer is interpreted as seconds. When omitted, ESPHome waits indefinitely for that interface. + +### Configuration variables (priority entries) + +- **interface** (**Required**, string): One of `ethernet`, `wifi`, `openthread`, or `modem`. The entry is written as the interface name itself (either as a string list item or as the single key of a mapping). Each interface may appear at most once. Every interface named here must also have its own top-level component block configured. +- **timeout** (*Optional*, [Time](/guides/configuration-types/#time)): How long to wait for this interface to come up before moving on to the next one in the list. Defaults to waiting indefinitely. + +> [!NOTE] +> Not every combination of interfaces is supported on every chip. WiFi and Ethernet may be used together on ESP32 family devices that have the necessary memory headroom; OpenThread and modem support depend on additional hardware and may be limited to specific variants. If `priority` is omitted, behavior is unchanged from earlier ESPHome releases and only a single interface component may be configured. + ## See Also - [WiFi Component](/components/wifi/) diff --git a/src/content/docs/components/wifi.mdx b/src/content/docs/components/wifi.mdx index 1436c3ee70..9fb58c7882 100644 --- a/src/content/docs/components/wifi.mdx +++ b/src/content/docs/components/wifi.mdx @@ -6,9 +6,10 @@ import APIRef from '@components/APIRef.astro'; This core ESPHome component sets up WiFi connections to access points -for you. You need to have a network configuration (either Wifi or Ethernet) -or ESPHome will fail in the config validation stage. You also can't have both Wifi -and Ethernet setup in same time (even if your ESP has both wired). +for you. You need to have a network configuration (either WiFi or [Ethernet](/components/ethernet/)) +or ESPHome will fail in the config validation stage. + +On ESP32 family devices, WiFi may be configured alongside [Ethernet](/components/ethernet/) in the same configuration; see [Multi-Interface Support](/components/network/#multi-interface-support) on the [Network](/components/network/) component for how to control which interface ESPHome prefers. On other platforms only one network interface may be configured at a time. It's recommended to provide a static IP for your node, as it can dramatically improve connection times.