Hypervision PLC: An Open-Source ESP32 PLC with Wired Ethernet via the WIZnet W5500

Summary

HypervisionPLC is an ESP32-based programmable logic controller that combines Modbus RTU, Modbus TCP connectivity, IEC 61131-3-style Structured Text execution, REST APIs, a web dashboard, counters, timers, and remote management in one firmware image. WIZnet's W5500 provides the wired Ethernet interface, connecting the PLC's ESP32 networking stack to industrial and supervisory applications through a physical LAN connection.

What the Project Does

HypervisionPLC turns an ESP32 into a small network-connected PLC rather than using it only as a simple Modbus I/O node.

At the field level, the controller can operate as a Modbus RTU slave over RS-485 so an HMI or SCADA system can access its coils and registers. It can also act as a Modbus master, polling external RTU devices asynchronously and caching their values so those transactions do not block the PLC's local logic execution.

The same register and coil storage is shared with an embedded Structured Text runtime. Up to four programs can execute PLC logic against the same data that Modbus clients, counters, timers, GPIO mappings, and REST clients use. The project implements an IEC 61131-3-inspired execution environment with data types, timers, counters, functions, function blocks, debugging, and persistent bytecode support.

The resulting architecture is roughly:

RS-485 / Modbus RTU ──────┐
                          │
Modbus TCP expansion ─────┤
                          ▼
                  Register / Coil Store
                          ↕
                  Structured Text VM
                          ↕
              GPIO / Counters / Timers
                          ↕
ESP32 ── W5500 ── Ethernet LAN
                    ├── REST API
                    ├── Web Dashboard
                    ├── SSE
                    ├── Telnet CLI
                    └── Networked PLC services

HypervisionPLC therefore combines traditional PLC interfaces with modern Ethernet management. A PLC can remain connected to legacy RS-485 devices while engineers access configuration, diagnostics, logic programs, and live process data over a browser or REST API.

Where WIZnet Fits

HypervisionPLC implements wired networking around the WIZnet W5500.

The repository contains a dedicated ethernet_driver.cpp whose purpose is a W5500 SPI Ethernet hardware abstraction. It initializes the SPI bus, checks that real W5500 silicon is responding, creates ESP-IDF W5500 MAC and PHY objects, attaches them to esp_netif, and manages DHCP, static addressing, link state, speed, duplex, and recovery.

For the ESP32-WROOM reference configuration, the project defines:

The W5500 support can be enabled at build time with ETHERNET_W5500_ENABLED. The project also includes a target for the Waveshare ESP32-S3-ETH board, which contains an onboard W5500.

One detail is important when interpreting the architecture.

HypervisionPLC does not use the W5500 in the conventional WIZnet ioLibrary model where the application opens the chip's hardware TCP/IP sockets directly. Instead, it uses Espressif's W5500 Ethernet driver and attaches the controller to ESP-IDF's TCP/IP stack.

In this configuration, the W5500 operates primarily as the SPI-connected Ethernet interface while the ESP32 networking stack handles IP, TCP, HTTP, and other upper-layer protocols.

The practical architecture is therefore:

ESP32 ↔ SPI ↔ W5500 ↔ 10/100 Ethernet LAN

rather than:

MCU ↔ W5500 hardware TCP/IP sockets

For a PLC, this still provides an important advantage: the controller has a dedicated wired network interface and does not need to depend solely on Wi-Fi.

The project supports Wi-Fi and Ethernet independently, and Ethernet can use either DHCP or a configured static IPv4 address.

Implementation Notes

W5500 Detection and SPI Initialization

File: src/ethernet_driver.cpp

HypervisionPLC does more than call an Ethernet library and assume that the controller exists. It explicitly configures the SPI bus and probes the W5500's VERSIONR register before starting the ESP-IDF Ethernet driver.

A shortened extract from the real implementation is:

spi_bus_config_t buscfg = {};
buscfg.miso_io_num = PIN_SPI_MISO;
buscfg.mosi_io_num = PIN_SPI_MOSI;
buscfg.sclk_io_num = PIN_SPI_CLK;

err = spi_bus_initialize(
    W5500_SPI_HOST,
    &buscfg,
    SPI_DMA_DISABLED
);

It then configures the W5500 as an SPI device:

spi_device_interface_config_t devcfg = {};
devcfg.command_bits = 16;
devcfg.address_bits = 8;
devcfg.mode = 0;
devcfg.clock_speed_hz = W5500_SPI_CLOCK_HZ;
devcfg.spics_io_num = PIN_SPI_CS;

These sections configure the physical SPI connection between the ESP32 and W5500. Keeping this logic inside a dedicated Ethernet driver isolates the hardware interface from the PLC application layer.

The firmware also reads the W5500 version register before allowing ESP-IDF to start the Ethernet driver:

t.cmd = 0x0039;
t.addr = 0x01;

esp_err_t probe_err =
    spi_device_polling_transmit(spi_handle, &t);

uint8_t version = t.rx_data[0];

if (probe_err != ESP_OK || version != 0x04) {
    return -1;
}

This check exists because a missing W5500 or incorrect SPI wiring can otherwise produce invalid readings from a floating MISO line. The firmware expects VERSIONR to return 0x04 before continuing.

For PLC hardware, this is a useful diagnostic distinction. It separates a missing or incorrectly connected Ethernet controller from later problems such as cable loss, DHCP failure, or network configuration errors.

Connecting W5500 to ESP-IDF Networking

After detecting the chip, HypervisionPLC creates the W5500 MAC and PHY instances used by ESP-IDF:

eth_w5500_config_t w5500_config =
    ETH_W5500_DEFAULT_CONFIG(spi_handle);

w5500_config.int_gpio_num = PIN_W5500_INT;

eth_mac_config_t mac_config =
    ETH_MAC_DEFAULT_CONFIG();

esp_eth_mac_t *mac =
    esp_eth_mac_new_w5500(
        &w5500_config,
        &mac_config
    );

It then creates the PHY and installs the Ethernet driver:

eth_phy_config_t phy_config =
    ETH_PHY_DEFAULT_CONFIG();

phy_config.reset_gpio_num = PIN_W5500_RST;

esp_eth_phy_t *phy =
    esp_eth_phy_new_w5500(&phy_config);

esp_eth_config_t eth_config =
    ETH_DEFAULT_CONFIG(mac, phy);

esp_eth_driver_install(
    &eth_config,
    &eth_state.eth_handle
);

The driver is subsequently attached to an ESP-IDF Ethernet network interface with esp_netif.

From that point onward, the PLC's higher-level services can use normal IP networking without directly accessing W5500 registers.

The architecture becomes:

PLC Application
     │
     ├── HTTP / REST
     ├── SSE
     ├── Telnet
     └── TCP-based PLC services
             │
           lwIP
             │
          esp_netif
             │
      ESP-IDF Ethernet
             │
           W5500
             │
          Ethernet

This separation keeps the PLC application largely independent from the physical Ethernet implementation.

Practical Tips / Pitfalls

• Pay attention to ESP32 boot pins. The project's ESP32-WROOM configuration assigns W5500 MISO to GPIO12, which is an ESP32 strapping pin. Hardware attached to that signal must not interfere with the required boot state.
• Use a defined W5500 reset state. The project documents hardware behavior around the W5500 reset signal, making the reset circuit an important part of a stable PLC design.
• Check the chip before checking the network. Reading VERSIONR and expecting 0x04 makes it possible to distinguish an SPI or hardware failure from an Ethernet link or IP configuration failure.
• Use static addressing when the PLC network requires predictable endpoints. HypervisionPLC supports both DHCP and static Ethernet configuration. Fixed SCADA and HMI installations often benefit from predictable addresses.
• Treat Ethernet link and IP state separately. A valid physical link does not automatically mean that the PLC has obtained a usable IP address.
• Do not assume W5500 hardware sockets are performing the TCP/IP processing. HypervisionPLC uses the W5500 through the ESP-IDF Ethernet driver, so TCP/IP processing remains in the ESP32 software networking stack.
• Test networking with the complete PLC workload. Structured Text execution, Modbus communication, HTTP, SSE, CLI services, counters, timers, and Ethernet can all operate concurrently. Cable removal, switch restart, DHCP loss, and repeated reboot tests are useful before deployment.

FAQ

Q: Why does HypervisionPLC use the W5500?

The W5500 adds a dedicated wired 10/100 Ethernet interface to the ESP32 over SPI. HypervisionPLC can use that interface for network management, web services, supervisory access, and TCP-based communication without making Wi-Fi the only available network path.

Q: How is the W5500 connected to the ESP32?

On the documented ESP32-WROOM configuration, the W5500 uses GPIO12 for MISO, GPIO13 for MOSI, GPIO14 for SCLK, and GPIO23 for chip select. GPIO34 receives the W5500 interrupt output, while GPIO33 is used for reset.

Q: What role does the W5500 play in this PLC?

The W5500 is HypervisionPLC's wired Ethernet interface. It connects the ESP32 PLC to an Ethernet LAN so higher-level services can expose PLC data, configuration, monitoring, and management functions over IP.

Q: Can beginners build HypervisionPLC with W5500?

The project is better suited to developers with intermediate embedded experience. Useful background includes PlatformIO, ESP32 GPIO and SPI, Ethernet addressing, Modbus, RS-485, and basic PLC concepts. Deeper development also involves FreeRTOS, ESP-IDF Ethernet APIs, register mapping, and Structured Text.

Q: How does W5500 Ethernet compare with Wi-Fi for HypervisionPLC?

Wi-Fi reduces physical wiring and can be convenient during development or in locations without Ethernet infrastructure. W5500 Ethernet adds cabling and SPI hardware, but provides a dedicated wired network path independent of RF conditions or Wi-Fi credentials. For fixed control cabinets and permanent PLC installations, wired Ethernet can therefore provide a simpler network topology.