---
title: "How to Integrate WIZnet W5500 SPI Ethernet on ESP-IDF for ESP32?"
url: "https://maker.wiznet.io/viktor/projects/eth-w5500/"
markdown_url: "https://maker.wiznet.io/viktor/projects/eth-w5500/md"
type: "UCC: User Created Content"
author: "Daniel Olaifa"
author_url: "https://github.com/drfhaust/eth-w5500"
editor: "WIZnet"
editor_url: "https://maker.wiznet.io/"
original_author: "Daniel Olaifa"
original_url: "https://github.com/drfhaust/eth-w5500"
published: "2026-02-09"
language: "en"
tags: ["ESP32"]
hardware: ["WIZnet W5500"]
likes: 0
views: 494
comments: 0
source: "WIZnet Makers (https://maker.wiznet.io/)"
---

# How to Integrate WIZnet W5500 SPI Ethernet on ESP-IDF for ESP32?

> The eth-w5500 project packages WIZnet’s W5500 (SPI Ethernet) into an ESP-IDF-friendly component with a small, struct-based API

Original author: Daniel Olaifa (source: https://github.com/drfhaust/eth-w5500)

## 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

## What the Project Does

This project is not an “end device” application—it’s a **reusable ESP-IDF component** that simplifies bringing up a W5500 module on ESP32-class targets. It aims to remove the usual glue code you write repeatedly (event loop setup, netif attach, DHCP/static IP selection, link/IP status tracking) and expose a minimal API (`init()`, `start()`, `wait_for_ip()`, status callbacks).

The Maker page describes it plainly as a “simple W5500 Ethernet driver for ESP-IDF… Pure C.”

## Where WIZnet Fits

The WIZnet part here is the **W5500**—a SPI-connected Ethernet controller used as the external wired network interface for an ESP32/ESP32-S2/ESP32-S3/etc. In this integration model, the ESP runs the IP stack (lwIP via ESP-IDF), while the W5500 provides the Ethernet link over SPI and is managed through ESP-IDF’s Ethernet driver framework.

This is a practical fit for maker builds where you want wired Ethernet without adding a separate MAC+PHY combination—just SPI pins (plus optional INT/RST) and a stable, cabled network path.

## Implementation Notes

### Drop-in component installation

The component is intended to be pulled directly into an ESP-IDF project using the component manager:

```plaintext
idf.py add-dependency "drfhaust/eth-w5500"
```

(From `README.md` in the project repository.)

### Minimal bring-up in `app_main()`

The README’s “Basic Usage (DHCP)” shows the intended flow: create a config struct, set SPI pins (at minimum CS plus the SPI signals if you’re not sharing an existing bus), then init + start:

```plaintext
eth_w5500_config_t cfg = ETH_W5500_DEFAULT_CONFIG();
cfg.spi_mosi = 23; cfg.spi_miso = 19; cfg.spi_clk = 18; cfg.spi_cs = 5;

eth_w5500_init(&cfg);
eth_w5500_start();
```

(From `README.md`.)

### What it links against in ESP-IDF

The component’s build file makes the intent clear: it is designed around ESP-IDF’s Ethernet and netif layers:

```plaintext
idf_component_register( SRCS "eth_w5500.c" INCLUDE_DIRS "include" REQUIRES driver esp_eth esp_netif esp_event )
```

(From `CMakeLists.txt`.)

For makers, this matters because it means your “real” application can use the usual ESP-IDF networking patterns (sockets, HTTP clients, mDNS, etc.) once the netif is up—without inventing a parallel stack.

## Practical Tips / Pitfalls

- **Decide early: shared SPI bus vs dedicated.** This project supports using an external SPI bus you already initialized, which is useful if you also have displays/sensors on SPI.

- **Be honest about INT pin availability.** If you don’t wire INT, plan for polling mode and keep your SPI wiring clean (short lines, good ground).

- **Treat DHCP timeouts as a first-class failure mode.** For maker demos, waiting is fine; for unattended installs, add a fallback (static IP, reboot strategy, or UI indicator).

- **Keep SPI clock in a conservative range.** The project documents an 8–25 MHz operating window in its configuration notes—start low when debugging signal integrity.

- **Reset strategy matters.** If your module exposes RST, wiring it gives you a recovery path when link negotiation or SPI gets wedged.

## FAQ

### Why choose the WIZnet W5500 for this kind of ESP-IDF maker build?

Because it’s a straightforward way to add wired Ethernet to ESP32-class boards using SPI, and it’s supported by ESP-IDF’s Ethernet driver model. You get a “normal” ESP-IDF netif that higher-level networking code can consume once the link is up and DHCP/static IP is configured.

### How does the W5500 connect to the platform in this project?

Over **SPI** (MOSI/MISO/SCLK/CS), with optional **INT** (or polling if INT is not wired) and optional **RST**. The component exposes these as fields in a config struct so you can map them to your specific board/module wiring.

### What role does the W5500 play in THIS project’s architecture?

It is the external Ethernet interface used by ESP-IDF’s Ethernet layer. The component’s job is to initialize the W5500-backed Ethernet driver, attach it to `esp_netif`, then provide simple status and control calls (start/stop, DHCP vs static IP, link/IP status).

### Can beginners follow this integration?

Yes—if you’re already able to build/flash an ESP-IDF project and you understand basic LAN concepts (DHCP, IP address, gateway). The “beginner traps” are almost always hardware: wrong CS pin, missing ground reference, or assuming INT is required when polling is acceptable (and vice versa).

### How does this compare to Espressif’s official W5500 driver/component?

Espressif’s official path is the `**espressif/w5500**` component (and the broader `**esp-eth-drivers**` ecosystem), which is designed to plug into ESP-IDF’s Ethernet layer as a standard driver building block.
This project (`drfhaust/eth-w5500`) is best viewed as a **convenience wrapper**: it keeps configuration in a plain struct (instead of leaning on menuconfig/Kconfig) and provides one-call helpers like “wait for IP” and status callbacks, while still relying on the same ESP-IDF Ethernet/netif foundations.
If you want maximum alignment with Espressif’s examples and long-term “standard” patterns, start with `espressif/w5500`. If you want a smaller integration surface for maker prototypes (fewer moving parts in your `app_main()`), this wrapper can be a faster on-ramp.

---

Source: https://maker.wiznet.io/viktor/projects/eth-w5500/