WT32-ETH01 ESP32 Gateway Module, Ethernet 10/100 Mbps, Wi-Fi, Bluetooth, 5V or 3.3V Power Supply

WT32-ETH01 is a board with an ESP32 and an Ethernet port, used in projects that need a wired connection more stable than Wi-Fi, for example automation nodes, gateways for serial devices or monitoring panels. In this tutorial we use the module alone, programmed from the Arduino IDE with the ESP32 Dev Module board, without any other development board.

The module has no USB port, so we program it through a CP2102 USB-TTL adapter with 3.3 V logic. At the end we will have a program that starts the Ethernet interface, displays the IP address received from the router and periodically checks that the network responds.

How it works:

The ESP32 contains the MAC controller for Ethernet, and the LAN8720A circuit on the board is the physical part (PHY) that talks to the cable. The two are connected through the RMII interface, which needs a 50 MHz reference clock. This clock comes from an oscillator on the board, started by the ESP32 through pin IO16, and enters the ESP32 on pin IO0. That is why in the program pin IO16 is declared as the power pin of the PHY and the clock is set to ETH_CLOCK_GPIO0_IN.

Pins IO23 (MDC) and IO18 (MDIO) form the management bus through which the ESP32 configures the LAN8720A, and the PHY address is 1. The actual data travels on the RMII pins IO19, IO21, IO22, IO25, IO26 and IO27, which are used internally and do not appear on the headers.

A few useful calculations. The serial port at 115200 baud transmits 10 bits for each byte (one start bit, 8 data bits and one stop bit), so approximately 115200 / 10 = 11520 bytes per second. Ethernet at 100 Mbps has a theoretical speed of 100 / 8 = 12.5 MB per second, which is over 1000 times faster. The average consumption is 80 mA, but the power source must be able to supply at least 500 mA for the current peaks of Wi-Fi and Ethernet. A USB port provides 500 mA, so it is sufficient.

Connection:

We power the module from the +5V pin of the CP2102 adapter, which passes the 5 V from USB directly through. We do not use the 3V3 pin of the adapter, because its regulator gives a small current, insufficient for an ESP32 with Wi-Fi. The signals are 3.3 V, so no level converter is needed, but never apply 5 V to the signal pins. The serial line is cross-connected: TXD of the adapter to RX0 and RXD of the adapter to TX0. Pin IO0 is connected to GND only while we upload the program.

Buttons, adjustments and indicators:

The board has no buttons, potentiometers, jumpers or switches. Starting in programming mode is done with a wire between IO0 and GND, and resetting is done with the EN pin. The status of the board is shown by three LEDs.

Programming mode. Connect the wire between IO0 and GND before powering the board or before resetting it. After the Arduino IDE finishes the upload, remove the wire and restart the power. If the serial monitor displays the message waiting for download, the wire is still connected or the board was not restarted.

Resetting. To restart the program without removing the power, touch the EN pin briefly to GND with a wire. The program restarts from the beginning and you will see the startup messages again on the serial monitor.

The POWER LED. When the adapter is connected to USB, it must light up immediately. This is the first sign that the power and ground are correct.

Board and libraries:

In the Arduino IDE, select the ESP32 Dev Module board from Tools > Board, from the esp32 package by Espressif Systems, installed from the Boards Manager. The package does not come with the Arduino IDE, so first add the address https://espressif.github.io/arduino-esp32/package_esp32_index.json under File > Preferences, at Additional boards manager URLs. The program was written for versions 2.0.x and 3.x of the package. Set the Upload Speed to 115200.

The program uses only the libraries that come with the ESP32 package (WiFi.h, ETH.h and WiFiClient.h), so no library needs to be installed from the Library Manager.

The code:

The program starts the Ethernet interface with the parameters specific to the WT32-ETH01 board, displays the network events and the IP address, and every 5 seconds attempts a TCP connection to the network gateway, that is the router, on port 80.

/*
  WT32-ETH01 Ethernet test: prints the IP address and checks the router
  Board (Arduino IDE, Tools > Board): ESP32 Dev Module
  Board package (Boards Manager): esp32 by Espressif Systems, versions 2.0.x or 3.x
  Boards Manager URL (File > Preferences):
    https://espressif.github.io/arduino-esp32/package_esp32_index.json
  Libraries: none to install. WiFi.h, ETH.h and WiFiClient.h come with the ESP32 package.
  Wiring (CP2102 USB to TTL adapter, 3.3 V logic):
    Adapter +5V -> module 5V pin (row 1)
    Adapter GND -> module GND pin next to 5V (row 1)
    Adapter TXD -> module RX0
    Adapter RXD -> module TX0
    Module IO0  -> module GND next to IO0 (row 2), only while uploading
    RJ45 port   -> router or switch with DHCP
*/
#include <WiFi.h>
#include <ETH.h>
// Ethernet PHY (LAN8720A) settings specific to the WT32-ETH01
#define WT_PHY_ADDR  1   // PHY address
#define WT_PHY_POWER 16  // GPIO16 enables the 50 MHz oscillator
#define WT_PHY_MDC   23  // Management clock pin
#define WT_PHY_MDIO  18  // Management data pin
static bool ethConnected = false;       // True after an IP address is received
static unsigned long lastCheck = 0;     // Time of the last network check
const unsigned long CHECK_INTERVAL = 5000;  // Check every 5 seconds
// Called by the system for every network event
void onEvent(WiFiEvent_t event) {
  switch (event) {
    case ARDUINO_EVENT_ETH_START:
      Serial.println("ETH started");
      ETH.setHostname("wt32-eth01");  // Name shown on the router
      break;
    case ARDUINO_EVENT_ETH_CONNECTED:
      Serial.println("ETH cable connected");
      break;
    case ARDUINO_EVENT_ETH_GOT_IP:
      Serial.print("ETH MAC: ");
      Serial.println(ETH.macAddress());
      Serial.print("IP address: ");
      Serial.println(ETH.localIP());
      Serial.print("Subnet mask: ");
      Serial.println(ETH.subnetMask());
      Serial.print("Gateway: ");
      Serial.println(ETH.gatewayIP());
      ethConnected = true;
      break;
    case ARDUINO_EVENT_ETH_DISCONNECTED:
      Serial.println("ETH cable disconnected");
      ethConnected = false;
      break;
    case ARDUINO_EVENT_ETH_STOP:
      Serial.println("ETH stopped");
      ethConnected = false;
      break;
    default:
      break;
  }
}
void setup() {
  Serial.begin(115200);  // Serial monitor on TX0 / RX0
  delay(500);
  Serial.println("WT32-ETH01 Ethernet test");
  WiFi.onEvent(onEvent);  // Register the event handler
  // The order of the arguments changed in version 3 of the ESP32 package
#if ESP_ARDUINO_VERSION_MAJOR >= 3
  ETH.begin(ETH_PHY_LAN8720, WT_PHY_ADDR, WT_PHY_MDC, WT_PHY_MDIO, WT_PHY_POWER, ETH_CLOCK_GPIO0_IN);
#else
  ETH.begin(WT_PHY_ADDR, WT_PHY_POWER, WT_PHY_MDC, WT_PHY_MDIO, ETH_PHY_LAN8720, ETH_CLOCK_GPIO0_IN);
#endif
}
void loop() {
  if (millis() - lastCheck < CHECK_INTERVAL) {
    return;  // Not time yet
  }
  lastCheck = millis();
  if (!ethConnected) {
    Serial.println("Waiting for an IP address...");
    return;
  }
  // Show the link speed and duplex mode
  Serial.print("Link: ");
  Serial.print((unsigned int)ETH.linkSpeed());
  Serial.print(" Mbps, ");
  Serial.println(ETH.fullDuplex() ? "full duplex" : "half duplex");
  // Try a TCP connection to the router on port 80 with a 3 second timeout
  WiFiClient client;
  if (client.connect(ETH.gatewayIP(), 80, 3000)) {
    Serial.println("Router reachable on port 80");
    client.stop();  // Close the connection
  } else {
    Serial.println("Router did not accept the connection on port 80");
  }
}

How the code works:

At the beginning we define the PHY parameters: WT_PHY_ADDR is address 1 of the LAN8720A circuit, WT_PHY_POWER is pin 16 which starts the oscillator, and WT_PHY_MDC and WT_PHY_MDIO are pins 23 and 18 of the management bus. The variable ethConnected stores whether we have received an IP address, and lastCheck stores the moment of the last check.

The onEvent function is called by the system for each network event. At ARDUINO_EVENT_ETH_START we set the host name with ETH.setHostname. At ARDUINO_EVENT_ETH_CONNECTED we know that the cable is connected. At ARDUINO_EVENT_ETH_GOT_IP we display the IP address, the mask and the gateway, and set ethConnected to true. At ARDUINO_EVENT_ETH_DISCONNECTED we set ethConnected to false.

In setup we start the serial monitor at 115200 baud, register the onEvent function with WiFi.onEvent and call ETH.begin. The order of the arguments of ETH.begin changed in version 3 of the ESP32 package, which is why the call is chosen with the ESP_ARDUINO_VERSION_MAJOR directive.

In loop we check every 5 seconds, using millis, whether the Ethernet is connected. If it is, we display the link speed with ETH.linkSpeed and the duplex mode, then we create a WiFiClient object and call client.connect to ETH.gatewayIP() on port 80, with a limit of 3000 ms. If the router accepts the connection, the network works completely and we close the connection with client.stop.

Result:

Open the serial monitor at 115200 baud after you have removed the IO0 - GND link and restarted the board. After a few seconds the messages below appear, with the IP address given by your router.

WT32-ETH01 Ethernet test
ETH started
ETH cable connected
ETH MAC: 24:6F:28:A1:5C:7E
IP address: 192.168.1.57
Subnet mask: 255.255.255.0
Gateway: 192.168.1.1
Link: 100 Mbps, full duplex
Router reachable on port 80
Link: 100 Mbps, full duplex
Router reachable on port 80

Common problems:

The upload stops with the error Failed to connect to ESP32. The cause is usually IO0 not connected to GND at power-up, or the TX and RX wires not cross-connected. Connect IO0 to GND, check that the TXD of the adapter goes to RX0 and RXD to TX0, then power the board again and retry the upload.

After the upload the serial monitor shows waiting for download. The wire between IO0 and GND is still connected. Remove it and restart the power.

Strange characters appear on the serial monitor. The serial monitor speed is not 115200 baud. Select this speed in the lower right corner of the monitor.

ETH started appears, but no IP address shows up. The cable is not connected, the router does not have DHCP enabled or the port is faulty. Check the cable, try another port on the router and watch whether the cable connected message appears.

The module resets by itself or freezes at startup. The power supply is insufficient or the voltage rises too slowly. Use the +5V pin of the adapter or a 5 V source with at least 500 mA, avoid powering from the 3V3 pin of the adapter and use short power wires.

The program does not compile and gives an error at ETH.begin. The installed ESP32 package is a different version from the expected one. Use a 2.0.x or 3.x version and keep the ESP32 Dev Module board selected.

Limitations and tips:

The module has a single 10/100 Mbps Ethernet port, without power over the network cable (PoE), so it always needs a separate power supply. Pins IO34 - IO39 are input only, and only IO35, IO36 and IO39 are brought out to the headers. The ADC2 inputs (IO2, IO4, IO12, IO14, IO15) cannot be read while Wi-Fi is on. Pins IO0, IO2 and IO12 are boot pins and must not be forced at startup.

The logic level is 3.3 V, so for 5 V equipment add a level converter. The module can operate between -40 °C and +85 °C, but it is good to protect it from humidity and vibration.

Further on, you can build a serial-to-Ethernet gateway using the TXD and RXD pins, a web server for controlling relays, an MQTT node for automation or a device with OTA firmware updates over the network.