---
title: "aux-2"
url: "https://maker.wiznet.io/jaden/resellers/aux-2/"
markdown_url: "https://maker.wiznet.io/jaden/resellers/aux-2/md"
type: "VAR: Value-Added Reseller Products"
author: "Nabucusa"
author_url: "https://github.com/NabuCasa/aux-2"
editor: "WIZnet"
editor_url: "https://maker.wiznet.io/"
original_author: "Nabucusa"
original_url: "https://github.com/NabuCasa/aux-2"
published: "2026-10-23"
language: "en"
hardware: ["WIZnet W5500"]
likes: 0
views: 4
comments: 0
source: "WIZnet Makers (https://maker.wiznet.io/)"
---

# aux-2

> aux-2

Original author: Nabucusa (source: https://github.com/NabuCasa/aux-2)

## Components

- **WIZnet W5500** x 1 ([docs](https://docs.wiznet.io/Product/Chip/Ethernet/W5500))

WIZnet parts: W5500 ([Datasheet](https://docs.wiznet.io/Product/Chip/Ethernet/W5500/datasheet?utm_source=maker&utm_medium=project&utm_campaign=w5500), [product hub](https://maker.wiznet.io/products/w5500/))

## Article

## How to Implement Automatic Ethernet and Wi-Fi Switching with WIZnet W5500 on ESP32-S3?

### 1. Summary

Home Assistant Connect AUX-2, developed by Nabu Casa, is an ESP32-S3-based smart home integration device that uses the WIZnet W5500 Ethernet controller to support wired networking alongside Wi-Fi. Built on ESPHome, the project integrates Bluetooth, Z-Wave, serial communication, and network audio. Its distinguishing feature is a custom W5500 PHY link monitor that detects Ethernet cable insertion and automatically switches between wired and wireless networking through persistent configuration and controlled reboots.

### 2. What the Project Does

Home Assistant Connect AUX-2 is designed to integrate devices using different communication interfaces into a single ESPHome-based platform.

Modern smart home environments often contain Bluetooth sensors, Z-Wave devices, RS-232/RS-485 equipment, and network audio systems. These interfaces require different hardware connections and software components.

AUX-2 combines these capabilities using an ESP32-S3 microcontroller.

The firmware configuration specifies a 240MHz CPU frequency, 8MB Flash, Octal PSRAM, and the ESP-IDF framework.

The project provides several functions:

**Bluetooth Proxy:** Relays communication between nearby Bluetooth devices and Home Assistant.

**Z-Wave Proxy:** Connects a USB-based Z-Wave adapter to the network.

**Serial Proxy:** Provides network connectivity for RS-232 and USB-based RS-485 interfaces.

**Sendspin Audio:** Receives and plays network audio streams from compatible services.

**Ethernet and Wi-Fi:** Provide IP connectivity for ESPHome services and connected devices.

The basic data flow is:

A Bluetooth sensor, Z-Wave adapter, or serial device communicates with the ESP32-S3.

An ESPHome component processes the incoming data.

The active network interface transfers data to Home Assistant or another compatible network service.

Commands or responses are delivered through the corresponding interface.

In Ethernet mode, the ESP32-S3 exchanges Ethernet frames with the W5500 through SPI. The W5500 then communicates with the external network using its integrated Ethernet MAC and PHY.

The main engineering feature is not simply adding an Ethernet interface. It is the firmware's ability to detect physical cable connections, select the appropriate network interface, and recover from certain connection failures.

### 3. Where WIZnet Fits

The WIZnet W5500 is a 10/100Mbps Ethernet controller with an SPI interface, integrated Ethernet MAC/PHY, hardware TCP/IP stack, eight hardware sockets, and 32KB of internal transmit/receive buffer memory.

In AUX-2, the W5500 provides the wired Ethernet interface for the ESP32-S3.

Because the W5500 communicates over SPI, Ethernet connectivity can be added without a separate RMII data bus. This is useful for a device that already uses Bluetooth, USB, UART, and I2S interfaces.

#### 3.1 W5500 Network Architecture

An important distinction is that the W5500's hardware TCP/IP capabilities are not necessarily used by every firmware implementation.

AUX-2 configures the controller using ESPHome's `ethernet: type: W5500` option and the ESP-IDF Ethernet driver.

According to Espressif's official W5500 driver documentation, the standard driver does not use the W5500's hardware TCP/IP stack. Instead, it operates the controller in MACRAW mode, with TCP/IP processing handled by the ESP32-S3's lwIP software stack.

The effective network architecture is:

**External devices → ESPHome components → ESP32-S3 lwIP stack → SPI → W5500 Ethernet MAC/PHY → Ethernet network**

This distinction matters when evaluating CPU offloading and socket limitations.

Although the W5500 supports eight hardware TCP/IP sockets, these hardware sockets are not used as eight application-level TCP/IP sockets in the standard MACRAW implementation.

Therefore, AUX-2 should be understood as a W5500-based SPI Ethernet implementation rather than an example of hardware TCP/IP offloading.

#### 3.2 Why W5500 Is Relevant to This Design

The W5500 contributes three practical capabilities.

**SPI-based Ethernet connectivity**

The controller provides wired Ethernet while requiring relatively few ESP32-S3 GPIO signals.

**Physical link status monitoring**

The firmware can directly read the W5500 PHY configuration register to determine whether an Ethernet cable is connected.

**Integration with firmware-level network management**

The device uses the W5500 link status to trigger interface selection and reboot-based recovery procedures.

AUX-2 supports both wired Ethernet and Wi-Fi, but the two interfaces are not operated as simultaneous active data paths in this configuration. The firmware activates one interface during each boot.

This makes the W5500 part of both the physical network architecture and the network selection mechanism.

### 4. Implementation Notes

#### 4.1 W5500 SPI Configuration

The W5500 Ethernet configuration is defined in `packages/aux-2.yaml`.

**Source:** [packages/aux-2.yaml, lines 84–94](https://github.com/NabuCasa/aux-2/blob/main/packages/aux-2.yaml#L84-L94)

```plaintext
ethernet:
  id: eth_component
  enable_on_boot: false
  type: W5500
  clock_speed: 80MHz
  clk_pin: 12
  mosi_pin: 11
  miso_pin: 13
  cs_pin: 10
  interrupt_pin: 14
  reset_pin: 39
```

The configuration assigns the following ESP32-S3 GPIO connections:

| W5500 Function | ESP32-S3 GPIO |
| --- | --- |
| SPI Clock (SCLK) | GPIO12 |
| SPI MOSI | GPIO11 |
| SPI MISO | GPIO13 |
| SPI Chip Select (CS) | GPIO10 |
| Interrupt | GPIO14 |
| Reset | GPIO39 |

The `clock_speed: 80MHz` setting configures the SPI communication clock. It does not represent a measured Ethernet throughput of 80Mbps.

The `enable_on_boot: false` setting is particularly important.

AUX-2 does not automatically start both Wi-Fi and Ethernet. Instead, its startup logic reads a persistent `use_wifi` flag and activates the selected interface.

This also prevents the Ethernet driver and custom W5500 link monitor from attempting to initialize the same SPI bus simultaneously.

#### 4.2 Detecting Ethernet Cable Insertion Through PHYCFGR

One of the project's most distinctive features is its custom ESPHome component, `w5500_link_monitor`.

Rather than relying only on network connection events, this component reads the W5500's PHY configuration register directly over SPI.

**Source:** [components/w5500_link_monitor/w5500_link_monitor.cpp, lines 101–110](https://github.com/NabuCasa/aux-2/blob/main/components/w5500_link_monitor/w5500_link_monitor.cpp#L101-L110)

```plaintext
uint8_t phycfgr;
if (!this->read_phycfgr_(&phycfgr)) {
  ESP_LOGW(TAG, "Failed to read PHYCFGR");
  return;
}
const bool link_up = (phycfgr & W5500_PHYCFGR_LNK_BIT) != 0;
```

The W5500 `PHYCFGR` register is located at address `0x002E`.

Bit 0, represented by `W5500_PHYCFGR_LNK_BIT`, indicates the physical link status:

**LNK = 1:** Ethernet physical link established.

**LNK = 0:** Ethernet physical link disconnected.

The `read_phycfgr_()` function performs the SPI register read using the ESP-IDF function `spi_device_polling_transmit()`.

The Python configuration in `components/w5500_link_monitor/__init__.py` defines a default polling interval of two seconds.

When the monitor detects a transition from Link Down to Link Up, it invokes the `on_link_up` callback.

Before invoking the callback, the component removes its SPI device and releases the SPI bus.

This prevents conflicts when the Ethernet driver initializes the same SPI host after the device switches to Ethernet mode.

The Python component also validates that the referenced Ethernet component uses `type: W5500`. SPI pins, clock speed, and host settings are inherited from the Ethernet configuration to prevent mismatched settings.

#### 4.3 Automatic Ethernet and Wi-Fi Switching

AUX-2 uses a persistent variable named `use_wifi` to determine which network interface should start.

The default value is `true`, meaning a new or factory-reset device initially starts in Wi-Fi mode.

##### Switching from Wi-Fi to Ethernet

While Wi-Fi is active, the W5500 link monitor periodically checks the physical Ethernet connection.

When a cable connection is detected:

The firmware changes `use_wifi` to `false`.

It saves the updated configuration using `global_preferences->sync()`.

It waits 500 milliseconds.

It restarts the ESP32-S3.

During the next boot, the Ethernet interface is enabled.

This approach allows the device to detect cable insertion without operating the full Ethernet network interface during Wi-Fi mode.

##### Switching from Ethernet to Wi-Fi

While Ethernet is active, the firmware monitors connection events.

If the Ethernet interface disconnects after previously reaching a connected state:

The firmware changes `use_wifi` to `true`.

It saves the updated configuration.

It waits 500 milliseconds.

It restarts the device.

The next boot enables Wi-Fi.

##### Ethernet Connection Failure During Boot

A separate recovery condition handles cases where Ethernet mode is selected but the interface never successfully connects.

The `eth_boot_connect_check` script in `packages/aux-2.yaml` waits for `ethernet.connected` for up to 30 seconds.

If the connection is not established within that period, the firmware switches the persistent setting to Wi-Fi and restarts.

This is necessary because an Ethernet interface that never reaches the connected state may not generate the same disconnect event as a previously established connection.

However, the timeout introduces a practical limitation. A physically connected cable with delayed DHCP configuration may still cause the firmware to fall back to Wi-Fi.

The link monitor can subsequently detect the cable and initiate another switch to Ethernet.

**The resulting behavior is automatic network switching, not seamless failover.**

Each interface transition requires a reboot. Existing TCP sessions, ESPHome API connections, and audio streams may therefore be interrupted.

#### 4.4 Factory Firmware Updates and Recovery

The repository also provides a separate factory firmware configuration in `packages/factory.yaml`.

This configuration includes:

RSA-3072 signature verification for OTA firmware.

OTA downgrade protection.

Device provisioning components.

HTTP-based firmware update delivery.

The factory firmware removes the standard ESPHome network OTA endpoint and uses a signed HTTP update channel.

Configurations adopted outside the factory firmware workflow can retain the standard ESPHome OTA mechanism.

This separation allows the product firmware to manage update authenticity while preserving different configuration options for device deployment.

For a commercially deployed smart home device, network recovery and firmware update management are separate but related design requirements.

The AUX-2 source addresses both through explicit firmware configuration.

### 5. Practical Tips and Pitfalls

When adapting this W5500 design to another ESP32-S3 or ESPHome project, several engineering details deserve attention.

**Validate SPI signal integrity.** The repository configures an 80MHz SPI clock. Actual performance and reliability depend on PCB routing, signal quality, supply stability, and electrical noise. Test the selected clock under the intended hardware conditions.

**Separate PHY link detection from IP connectivity.** A valid PHY link only confirms physical Ethernet connectivity. It does not guarantee DHCP completion, IP routing, DNS resolution, or successful Home Assistant communication.

**Manage SPI bus ownership explicitly.** The custom monitor and Ethernet driver use the same SPI resources. Their initialization and cleanup procedures must prevent simultaneous ownership of the SPI host.

**Review DHCP and connection timeouts.** The 30-second Ethernet connection timeout is a recovery mechanism, but it may be unsuitable for networks with consistently slow address assignment.

**Plan for session interruption.** Network switching requires rebooting the device. ESPHome API sessions, serial proxy connections, and network audio streams must reconnect after the selected interface starts.

**Consider Ethernet protection and installation conditions.** RJ45 isolation, ESD protection, grounding, cable quality, and EMI susceptibility should be evaluated for long-term or electrically noisy installations.

The repository demonstrates the network selection and recovery mechanisms in source code. It does not establish a measured CPU utilization reduction, guaranteed recovery time, or seamless service availability.

Those metrics would require separate testing under defined network conditions.

### 6. FAQ

#### Q1. Why does Home Assistant Connect AUX-2 use the WIZnet W5500?

The W5500 provides 10/100Mbps wired Ethernet connectivity to the ESP32-S3 through an SPI interface without requiring a separate RMII data bus.

This is useful for AUX-2 because the platform also uses Bluetooth, USB, UART, and audio interfaces.

The W5500 additionally exposes physical Ethernet link status through its PHY configuration register, enabling the firmware to detect cable insertion and initiate automatic network switching.

#### Q2. How is the W5500 connected to the ESP32-S3?

The controller uses SPI.

In AUX-2, GPIO12 is assigned to SCLK, GPIO11 to MOSI, GPIO13 to MISO, and GPIO10 to Chip Select. GPIO14 provides the interrupt connection, while GPIO39 is used for reset.

The SPI clock is configured at 80MHz through ESPHome's Ethernet component.

The custom link monitor inherits these SPI settings from the Ethernet configuration.

#### Q3. What exactly does the W5500 do in AUX-2?

The W5500 provides the wired Ethernet MAC/PHY interface and transfers Ethernet frames between the ESP32-S3 and the external network.

This connectivity supports IP-based services such as ESPHome API communication, network audio, and device proxy functions.

A separate custom component reads the W5500 `PHYCFGR` register to monitor physical cable connectivity.

When a cable is detected during Wi-Fi operation, the firmware uses this information to select Ethernet for the next boot.

The W5500 does not directly implement Bluetooth, Z-Wave, or serial communication protocols.

#### Q4. Can beginners reproduce this W5500 implementation?

Developers familiar with ESP32-S3 GPIO configuration, SPI communication, and ESPHome YAML files should be able to understand the basic Ethernet configuration.

Reproducing the full automatic switching mechanism requires additional knowledge of ESP-IDF SPI drivers, W5500 registers, ESPHome custom components, nonvolatile configuration storage, and reboot behavior.

The complete implementation is therefore better suited to developers with intermediate embedded firmware experience.

#### Q5. How does W5500 Ethernet compare with Wi-Fi or software TCP/IP networking?

Wired Ethernet avoids wireless channel interference and signal-strength variations, making it suitable for fixed smart home gateways with accessible network cabling.

Wi-Fi provides installation flexibility but depends on wireless coverage and channel conditions.

The W5500 contains a hardware TCP/IP stack, but the standard ESP-IDF Ethernet driver used by this implementation operates in MACRAW mode. TCP/IP processing is therefore handled by the ESP32-S3's lwIP software stack.

Consequently, AUX-2 should not be presented as evidence of reduced CPU utilization through W5500 TCP/IP offloading.

Its demonstrated engineering contribution is the combination of a wired Ethernet interface, physical link monitoring, and firmware-controlled network selection.

### 7. Source

**Project:** Home Assistant Connect AUX-2

**Original developer:** Nabu Casa

**Original repository:**
<https://github.com/NabuCasa/aux-2>

**Verified source files:**

ESPHome configuration and Ethernet interface setup
`packages/aux-2.yaml`
<https://github.com/NabuCasa/aux-2/blob/main/packages/aux-2.yaml>

W5500 PHY link monitoring implementation
`components/w5500_link_monitor/w5500_link_monitor.cpp`
<https://github.com/NabuCasa/aux-2/blob/main/components/w5500_link_monitor/w5500_link_monitor.cpp>

Link monitor configuration and SPI parameter inheritance
`components/w5500_link_monitor/__init__.py`
<https://github.com/NabuCasa/aux-2/blob/main/components/w5500_link_monitor/__init__.py>

Factory firmware update configuration
`packages/factory.yaml`
<https://github.com/NabuCasa/aux-2/blob/main/packages/factory.yaml>

**Technical references:**

WIZnet W5500 product information:
<https://wiznet.io/products/ethernet-chips/w5500>

Espressif W5500 Ethernet driver documentation:
<https://github.com/espressif/esp-eth-drivers/blob/master/w5500/README.md>

**License:**

The repository includes the ESPHome licensing structure, describing GPLv3 for C/C++ runtime code and MIT licensing for Python and other files. Applicable license requirements and copyright notices should be reviewed before redistributing or modifying source code.

Repository license:
<https://github.com/NabuCasa/aux-2/blob/main/LICENSE>

**Source reviewed:** October 23, 2026

### 8. Tags

#W5500 #WIZnet #ESP32S3 #ESPHome #HomeAssistant #NabuCasa #Ethernet #SmartHome #SPI #NetworkFailover #IoT #W5500LinkMonitor

---

Source: https://maker.wiznet.io/jaden/resellers/aux-2/