esphome-ipv6-only

How to Run IPv6-Only ESPHome with WIZnet W5500 on ESP32-S3?

1. Summary

The esphome-ipv6-only project by David Coulson enables ESPHome devices to operate without an IPv4 address or DHCPv4 server. It includes an Ethernet configuration for the Waveshare ESP32-S3-ETH board, which uses the WIZnet W5500 over SPI. The W5500 provides wired Ethernet frame transmission, while the ESP32-S3 runs the lwIP software stack to handle IPv6 networking. The project also modifies ESPHome's connection logic, IPv6 address initialization, DNS, and SNTP behavior, providing a practical approach to IPv6-only home automation.

2. What the Project Does

The Problem: ESPHome Depends on IPv4 Connectivity

ESPHome connects microcontrollers to Home Assistant through Wi-Fi or Ethernet. However, the original ESPHome implementation contains network initialization logic that depends on obtaining an IPv4 address.

For example, its Wi-Fi component historically initiated IPv6 link-local address creation after receiving a DHCPv4 address. On a network without DHCPv4, the device could remain in the connecting state even when IPv6 Router Advertisements were available.

The esphome-ipv6-only project addresses this limitation by modifying ESPHome's networking components.

Its main changes include:

IPv6-only operation: Adds network: enable_ipv4: false, allowing connectivity without an IPv4 address.

IPv6 address initialization: Starts link-local address configuration independently of DHCPv4.

SLAAC support: Uses IPv6 Router Advertisements to obtain addresses and default-router information.

DNS configuration: Supports IPv6 DNS information through RDNSS (RFC 8106) and stateless DHCPv6.

SNTP improvements: Resolves IPv6 addresses first when selecting time servers.

Ethernet recovery: Retries failed IPv6 link-local address initialization instead of relying on a single attempt.

The project provides modified components for ESPHome 2026.9.0 and includes test configurations for both Wi-Fi and Ethernet devices.

System Architecture

The W5500-based configuration follows this data path:

     Home Assistant / NTP Server
                |
          IPv6 Network
                |
          Ethernet Switch
                |
         WIZnet W5500
       Ethernet MAC / PHY
                |
           SPI (25 MHz)
                |
            ESP32-S3
                |
       ESP-IDF Ethernet Driver
                |
          lwIP IPv6 Stack
                |
       ESPHome Application

The W5500 transfers Ethernet frames between the physical network and the ESP32-S3.

The ESP32-S3 handles IPv6 addressing, TCP/UDP communication, DNS resolution, and ESPHome application functions.

This separation is important because the W5500's hardware TCP/IP stack does not support IPv6 directly.

3. Where WIZnet Fits

W5500 as an Ethernet Interface for Software IPv6

The project's Ethernet test configuration targets the Waveshare ESP32-S3-ETH, combining an ESP32-S3 microcontroller with a WIZnet W5500 Ethernet controller.

The W5500 normally provides a hardware TCP/IP stack supporting IPv4, TCP, and UDP, with eight hardware sockets and 32 KB of internal buffer memory.

However, the ESP-IDF Ethernet driver uses the W5500 differently.

According to Espressif's official W5500 driver documentation, the chip's built-in hardware TCP/IP stack is not used by the ESP driver.

Instead, Ethernet frames are transferred through the W5500's MAC RAW functionality, and lwIP processes the IP protocols on the ESP32-S3.

The W5500 is not performing IPv6 TCP/IP hardware offloading in this project.

This distinction matters when evaluating CPU usage and memory requirements.

Although the W5500 contains a dedicated hardware TCP/IP engine, the ESP32-S3 remains responsible for IPv6 processing in this implementation. The W5500's eight hardware sockets are not used to offload IPv6 TCP connections.

The practical benefit is that an existing W5500-based ESP32 board can support IPv6 networking through its software stack without replacing the Ethernet hardware.

W5500-Specific SPI Transfer Optimization

Another notable implementation detail is the project's custom W5500 SPI driver.

The repository includes:

components/ethernet/w5500_custom_spi.cpp

This driver changes how Ethernet frame payloads are transferred over SPI.

Small register transfers use polling, while larger transfers use the ESP-IDF blocking SPI transaction API, allowing the calling task to sleep while DMA transfers the data.

The implementation uses a 64-byte threshold to distinguish small transfers from bulk frame payloads.

This optimization reduces busy-waiting by design, but the repository does not provide measured CPU utilization or throughput improvements attributable to it.

It is also separate from W5500 hardware TCP/IP offloading: the optimization concerns SPI data transfer, not TCP/IP protocol execution.

4. Implementation Notes

4.1. ESP32-S3 and W5500 Configuration

The repository provides an Ethernet test configuration for the Waveshare ESP32-S3-ETH board.

Source: s3-eth-test.yaml, lines 25–44

external_components:
  - source:
      type: local
      path: components
    components: [network, ethernet, ethernet_info, sntp]

network:
  enable_ipv6: true
  min_ipv6_addr_count: 2
  enable_ipv4: false

ethernet:
  type: W5500
  mosi_pin: GPIO11
  miso_pin: GPIO12
  clk_pin: GPIO13
  cs_pin: GPIO14
  reset_pin: GPIO9
  interrupt_pin: GPIO10
  clock_speed: 25MHz

The external_components section loads the project's modified networking components from the local repository directory.

The network section enables IPv6 and disables the requirement for IPv4.

The ethernet section configures the W5500 SPI interface.

The original Waveshare board uses the following assignments:

These values are specific to the Waveshare ESP32-S3-ETH configuration. Different W5500 boards may require different GPIO assignments.

The min_ipv6_addr_count: 2 setting requires at least two IPv6 addresses before the network is considered connected.

Typically, these include a link-local address and an additional SLAAC-configured address.

This prevents the device from reporting network readiness based only on a link-local address when communication beyond the local network segment is required.

4.2. Custom SPI Transfer Handling

The W5500-specific driver uses different SPI transaction methods depending on transfer size.

Source: components/ethernet/w5500_custom_spi.cpp, lines 55–67

esp_err_t ret;
if (len > W5500_SPI_BULK_THRESHOLD) {
  ret = spi_device_transmit(ctx->handle, trans);
} else {
  ret = spi_device_polling_transmit(ctx->handle, trans);
}
xSemaphoreGive(ctx->lock);
return ret;

The source defines W5500_SPI_BULK_THRESHOLD as 64 bytes.

For transfers larger than 64 bytes, spi_device_transmit() performs a blocking, interrupt-driven transaction.

For smaller register accesses, spi_device_polling_transmit() avoids the overhead associated with interrupt-driven transfers.

The driver also uses a mutex to protect shared SPI access, with a configured lock timeout of 50 milliseconds.

The Ethernet initialization code installs this custom transfer implementation through install_w5500_async_spi(w5500_config) before constructing the W5500 MAC driver.

This is a concrete firmware modification specific to W5500 operation in the repository.

4.3. Removing DHCPv4 Dependency

The project also modifies Ethernet connection handling.

Source: components/ethernet/ethernet_component_esp32.cpp, lines 872–883

When USE_NETWORK_IPV6_ONLY is defined, the firmware leaves the DHCPv4 client stopped rather than restarting it.

This is necessary because the original network initialization process can depend on DHCPv4 before establishing the default network interface.

The modified connection logic instead evaluates the number of configured IPv6 addresses.

The relevant IPv6 event handler is implemented in the same file, at lines 717–741.

Importantly, this change does not remove IPv4 support from lwIP at compile time. It changes how the ESPHome device initializes its interface and determines whether networking is ready.

4.4. IPv6 Link-Local Address Recovery

The original Ethernet component could fail to initialize an IPv6 link-local address during startup or after a link interruption.

The modified firmware checks the address state and retries initialization approximately every 5 seconds when necessary.

It also detects duplicate address detection failures and reports them through the logging system.

This behavior applies to Ethernet configurations using the modified component, including W5500 devices.

In IPv6-only operation, successful link-local address creation is important because it enables the subsequent Neighbor Discovery and SLAAC processes.

4.5. Hardware Test Results

The repository documents testing with ESPHome 2026.9.0 and ESP-IDF 5.5.5 and 6.1.0.

The author reports the following results:

The ESP32-S3/W5500 hardware results were obtained using ESP-IDF 6.1.0.

The W5500-based GPS NTP board successfully obtained IPv6 addresses and a Router Advertisement default route, and served NTP over IPv6.

However, the repository's explicitly documented comprehensive IPv6-only test—covering Home Assistant connectivity and OTA updates—was performed on the ESP32-C3 Wi-Fi platform.

Therefore, the W5500 Ethernet implementation demonstrates IPv6 capability, but the published results should not be interpreted as comprehensive validation of every ESPHome feature in W5500 IPv6-only mode.

Source: README — Ethernet and hardware testing

5. Practical Tips / Pitfalls

Check SPI hardware configuration. The original example uses a 25 MHz SPI clock and GPIO11–14 for SPI signals. Custom boards should verify their pin assignments, signal quality, and power supply.

Check Ethernet link and IPv6 status independently. A physical Ethernet link does not guarantee successful IPv6 configuration. Confirm link-local and SLAAC addresses in the ESPHome logs.

Configure Router Advertisements. IPv6-only networks require appropriate SLAAC prefixes and router information. DNS configuration may also require RDNSS or stateless DHCPv6 support.

Verify IPv6 multicast reception. SLAAC depends on IPv6 Neighbor Discovery and Router Advertisements. The repository reports that W5500 passes IPv6 multicast traffic, while certain ESP32 internal Ethernet MAC configurations require additional multicast filtering adjustments.

Use IPv6-capable network services. The project's SNTP configuration uses 2.pool.ntp.org. Other services, including MQTT brokers and HTTP endpoints, must also provide reachable IPv6 addresses or use appropriate transition mechanisms.

Account for software IPv6 processing. W5500 does not offload IPv6 TCP/IP processing in this ESP-IDF configuration. CPU load, RAM consumption, SPI throughput, and latency should be measured when adding higher-bandwidth applications.

Maintain version compatibility. The repository is based on ESPHome 2026.9.0. Upgrading ESPHome or ESP-IDF may require updating the modified networking components.

6. FAQ

Q1. Why use WIZnet W5500 for IPv6-only ESPHome networking?

The W5500 provides a wired Ethernet interface for ESP32-S3 devices through SPI. Although its internal TCP/IP stack is designed for IPv4, the ESP-IDF driver allows Ethernet frames to be processed by the ESP32-S3's lwIP software stack. This enables IPv6 networking on existing W5500-based hardware without requiring a different Ethernet controller.

Q2. How is W5500 connected to ESP32-S3 in this project?

The Waveshare ESP32-S3-ETH configuration connects W5500 through SPI using GPIO11 for MOSI, GPIO12 for MISO, GPIO13 for SCK, and GPIO14 for CS. GPIO9 provides reset control, while GPIO10 handles the interrupt signal. The example uses a 25 MHz SPI clock, configured through ESPHome's ethernet: component with type: W5500.

Q3. Does W5500 perform IPv6 TCP/IP hardware offloading in this project?

No. The W5500 transfers Ethernet frames through its MAC RAW functionality, while lwIP on the ESP32-S3 processes IPv6 and TCP/UDP protocols. The repository also introduces a custom SPI transfer driver that uses DMA-backed transactions for larger frame transfers, but this is an SPI transfer optimization rather than hardware TCP/IP offloading.

Q4. Can beginners implement IPv6-only ESPHome with W5500?

Developers who already understand ESPHome YAML configuration and ESP32 networking can use the repository as a starting point. However, IPv6-only deployment requires knowledge of SPI hardware configuration, ESP-IDF, SLAAC, Router Advertisements, and IPv6 DNS. The original project provides example configurations, but network troubleshooting may require intermediate embedded networking experience.

Q5. How does W5500 Ethernet compare with Wi-Fi for IPv6-only ESPHome devices?

Both W5500 Ethernet and ESP32 Wi-Fi can use lwIP for IPv6 networking. W5500 provides a wired connection that avoids wireless interference and access-point association problems, making it suitable for stationary devices. Wi-Fi offers easier installation where Ethernet cabling is unavailable. The project separately tests IPv6-only Wi-Fi on ESP32-C3 and IPv6 connectivity over W5500 Ethernet on ESP32-S3. It does not establish a comparative throughput or latency advantage between the two configurations.

7. Source

Original Project: davidcoulson/esphome-ipv6-only

Author: David Coulson

License: MIT License — Copyright © 2026 David Coulson

Software Baseline: ESPHome 2026.9.0

Source reviewed: October 26, 2026

Original Repository Files

Official Technical References

WIZnet W5500 Product Documentation

Espressif W5500 Ethernet Driver

ESPHome Ethernet Component Documentation

8. Tags

#W5500 #WIZnet #ESP32S3 #ESPHome #IPv6 #Ethernet #SPI #HomeAssistant #ESPIDF #lwIP #SLAAC #IoT