ESP-IDF Template

1. Overview

esp32-eth-wifi-mqtt is an ESP-IDF based connectivity firmware that combines W5500 SPI Ethernet, WiFi Station, and MQTT client on a single ESP32 platform.

The main goal of this project is to provide a practical networking template for IoT devices that require both wired and wireless connectivity. The firmware initializes W5500 Ethernet over SPI and WiFi Station mode, attaches both network interfaces to esp-netif, and starts an MQTT client that connects to a configured broker once network connectivity is available. The project description in the repository summarizes it as “ESP32 + W5500 SPI Ethernet + WiFi STA on esp-netif, connecting to an MQTT broker.”

IoT devices often face several connectivity challenges:

WiFi signal quality can vary depending on installation location.
Wired Ethernet is more stable but not always available.
MQTT broker settings often need to be changed depending on the deployment environment.
Embedded network applications need clear event logging for link, IP, and broker connection states.

To address these issues, this project provides:

Dual network interface initialization using Ethernet and WiFi.
W5500 SPI Ethernet support through ESP-IDF Ethernet driver configuration.
WiFi Station mode with automatic reconnect behavior.
MQTT client startup using configurable broker URI, username, and password.
Event-based logging for Ethernet, WiFi, IP, and MQTT states.

2. System Architecture

The firmware is organized around three main connectivity blocks: Ethernet, WiFi, and MQTT.

            ESP32 Application
                   │
                   ▼
        Initialize NVS / esp-netif / Event Loop
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
 W5500 SPI Ethernet      WiFi Station
        │                     │
        └──────────┬──────────┘
                   ▼
              esp-netif
                   ▼
            TCP/IP Network Stack
                   ▼
              MQTT Client
                   ▼
              MQTT Broker

The application entry point initializes NVS, initializes esp_netif, creates the default event loop, starts Ethernet, starts WiFi, and then starts MQTT. This order is visible in app_main(), where app_ethernet_init(), app_wifi_init(), and app_mqtt_init() are called sequentially.

The firmware is split into separate modules:

main/
├── main.c
├── inc/
│   ├── ethernet_interface.h
│   ├── wifi_interface.h
│   └── mqtt_interface.h
└── src/
    ├── ethernet_interface.c
    ├── wifi_interface.c
    └── mqtt_interface.c

components/
└── ethernet_init/
    ├── ethernet_init.c
    ├── ethernet_init.h
    ├── CMakeLists.txt
    └── Kconfig.projbuild

The GitHub repository shows this separation through main/inc, main/src, and components/ethernet_init, which contain the Ethernet, WiFi, MQTT, and low-level Ethernet initialization code.

3. Core Modules

3.1 Ethernet Interface — W5500 over SPI

The Ethernet module initializes the Ethernet driver, creates an esp-netif Ethernet instance, attaches the Ethernet driver to the TCP/IP stack, registers Ethernet/IP event handlers, and starts the Ethernet state machine.

The Ethernet event handler logs major link states:

Ethernet Link Up
Ethernet Link Down
Ethernet Started
Ethernet Stopped
Ethernet Got IP Address

The implementation registers handlers for ETH_EVENT and IP_EVENT_ETH_GOT_IP, then starts each Ethernet handle with esp_eth_start().

For a single Ethernet interface, the project uses ESP_NETIF_DEFAULT_ETH(). For multiple Ethernet interfaces, it creates separate interface keys and descriptions such as ETH_0, eth0, and adjusts route priority per interface.

3.2 WiFi Station Interface

The WiFi module configures ESP32 as a WiFi Station. It creates a default WiFi STA network interface, initializes the WiFi driver, registers event handlers, configures SSID/password, and starts WiFi.

The WiFi event handler performs automatic reconnect when disconnected:

WIFI_EVENT_STA_START        → esp_wifi_connect()
WIFI_EVENT_STA_DISCONNECTED → retry connection
IP_EVENT_STA_GOT_IP         → log assigned IP address

The implementation uses CONFIG_ESP_WIFI_SSID and CONFIG_ESP_WIFI_PASSWORD from Kconfig, then sets the ESP32 into WIFI_MODE_STA and starts the WiFi driver.

3.3 MQTT Client

The MQTT module starts an ESP-MQTT client using the broker URI and optional credentials defined in project configuration.

The MQTT event handler logs:

MQTT connected to broker
MQTT disconnected from broker
MQTT subscribed
MQTT published
MQTT data received
MQTT event error

The MQTT client configuration uses:

.broker.address.uri = CONFIG_MQTT_BROKER_URI
.credentials.username = CONFIG_MQTT_USERNAME
.credentials.authentication.password = CONFIG_MQTT_PASSWORD

After configuration, the project initializes the client, registers the MQTT event handler, and starts the MQTT client.

ESP-MQTT is Espressif’s MQTT protocol client implementation and supports common MQTT communication use cases such as TCP, TLS, WebSocket, and MQTT v5 examples.

4. Dual Interface Connectivity Model

The key design idea of this project is to keep both wired and wireless interfaces available in one firmware.

Ethernet available
      ↓
Use W5500 wired network path

WiFi available
      ↓
Use WiFi Station network path

MQTT client
      ↓
Connects through available TCP/IP network interface

In main.c, the project comment states that both W5500 Ethernet and WiFi Station are attached to esp-netif, and that Ethernet has higher route priority by default before the MQTT client connects to the configured broker.

This model is useful because the application logic does not need to directly manage every low-level network path. Instead, the firmware brings up both interfaces, and the TCP/IP stack handles the available route based on interface state and priority.

5. Configuration

The project exposes important settings through Kconfig.

WiFi Configuration

WiFi SSID
WiFi Password
WPA3 SAE mode
Maximum retry
WiFi scan auth mode threshold

The WiFi configuration menu includes SSID, password, WPA3 SAE mode selection, maximum retry count, and authentication mode threshold. The default SSID and password are set as TEST and TEST1234, which should be changed for real deployments.

MQTT Configuration

MQTT broker URI
MQTT username
MQTT password

The MQTT broker URI defaults to:

mqtt://192.168.1.100:1883

The same Kconfig section also provides username and password fields for broker authentication.

Ethernet Configuration

The Ethernet component is configured to use external SPI Ethernet by default, with W5500 selected as the default SPI Ethernet module.

Default ESP32 SPI pin settings include:

SCLK : GPIO18
MOSI : GPIO23
MISO : GPIO19
CS0  : GPIO5
INT0 : GPIO15
RST0 : GPIO4

These defaults come from the Ethernet Kconfig settings for ESP32 targets, and they match the main project comment that lists MOSI 23, SCLK 18, MISO 19, RST 4, and INT 15 for the ESP32-W5500 connection.

6. Technology Stack

Core Framework

ESP-IDF
FreeRTOS
ESP event loop
NVS flash
esp-netif
ESP Ethernet driver
ESP WiFi driver
ESP-MQTT client

The main component’s CMake file requires esp_eth, esp_netif, esp_wifi, esp_event, nvs_flash, mqtt, and ethernet_init, which reflects the project’s core software stack.

Minimum ESP-IDF Version

The project manifest specifies ESP-IDF version >=5.0.

Network Interfaces

W5500 SPI Ethernet
WiFi Station
MQTT over TCP/IP

Configuration Method

Kconfig / menuconfig
Compile-time SSID, password, broker URI, and Ethernet pin configuration

Connection to W5500

W5500 is the wired Ethernet interface used by this project.

WIZnet describes W5500 as a hardwired Internet controller with an integrated TCP/IP stack, 10/100 Ethernet MAC and PHY, and SPI connectivity.

In this firmware, W5500 is connected to the ESP32 through SPI and used as an external Ethernet controller. The project’s Ethernet Kconfig selects SPI Ethernet by default and sets W5500 as the default SPI Ethernet type.

The practical ESP32-W5500 wiring is:

ESP32 GPIO	W5500 Signal
GPIO23	MOSI
GPIO18	SCLK
GPIO19	MISO
GPIO5	CS
GPIO4	RST
GPIO15	INT
3.3V	VCC
GND	GND

This makes the project suitable for IoT gateways, industrial sensors, and edge devices that need stable Ethernet connectivity while still keeping WiFi available as an additional network interface.

7. Applications

Use Cases

ESP32 IoT gateway with wired Ethernet and WiFi connectivity
MQTT-based sensor node
Industrial monitoring device
Smart factory data collection endpoint
Home automation bridge
Ethernet-first IoT controller with WiFi fallback
MQTT test platform for ESP-IDF networking
W5500 evaluation firmware for ESP32

Value Proposition

This project provides a compact starting point for ESP32 network applications that need more than basic WiFi.

It combines:

W5500 SPI Ethernet
        +
WiFi Station
        +
esp-netif
        +
MQTT Client

The result is a reusable ESP-IDF firmware structure for MQTT-based IoT devices where wired connectivity, wireless connectivity, and broker communication are all initialized in a clean modular way.

8. Conclusion

esp32-eth-wifi-mqtt is a practical ESP-IDF project for building ESP32 devices that communicate with an MQTT broker through both W5500 Ethernet and WiFi Station interfaces.

Through its modular structure, the project separates:

Ethernet initialization
WiFi Station connection
MQTT client operation
Project-level configuration

The W5500 interface provides stable wired Ethernet connectivity, while WiFi Station mode gives the device a second network path. MQTT then provides a lightweight publish/subscribe communication layer for IoT applications.

This makes the project a useful foundation for ESP32-based industrial IoT, smart home, gateway, monitoring, and remote telemetry systems that require reliable network connectivity with MQTT integration.