Modulo gateway WT32-ETH01 ESP32, Ethernet 10/100 Mbps, Wi-Fi, Bluetooth, alimentazione 5V o 3.3V

WT32-ETH01 è una scheda con ESP32 e porta Ethernet, utilizzata in progetti che necessitano di un collegamento via cavo più stabile del Wi-Fi, ad esempio nodi di automazione, gateway per apparecchiature seriali o pannelli di monitoraggio. In questo tutorial usiamo il modulo da solo, programmato da Arduino IDE con la scheda ESP32 Dev Module, senza alcuna altra scheda di sviluppo.

Il modulo non ha porta USB, quindi lo programmiamo tramite un adattatore USB-TTL CP2102 con logica a 3.3 V. Alla fine avremo un programma che avvia l'Ethernet, mostra l'indirizzo IP ricevuto dal router e verifica periodicamente che la rete risponda.

Come funziona:

L'ESP32 contiene il controller MAC per Ethernet, mentre il circuito LAN8720A presente sulla scheda è la parte fisica (PHY) che comunica con il cavo. I due si collegano tramite l'interfaccia RMII, che richiede un clock di riferimento a 50 MHz. Questo clock arriva da un oscillatore presente sulla scheda, avviato dall'ESP32 tramite il pin IO16, ed entra nell'ESP32 sul pin IO0. Per questo motivo nel programma il pin IO16 è dichiarato come pin di alimentazione del PHY e il clock è impostato su ETH_CLOCK_GPIO0_IN.

I pin IO23 (MDC) e IO18 (MDIO) formano il bus di gestione con cui l'ESP32 configura il LAN8720A, mentre l'indirizzo PHY è 1. I dati veri e propri circolano sui pin RMII IO19, IO21, IO22, IO25, IO26 e IO27, che sono usati internamente e non compaiono sui connettori a barra.

Qualche calcolo utile. La porta seriale a 115200 baud trasmette 10 bit per ogni byte (un bit di start, 8 bit di dati e un bit di stop), quindi circa 115200 / 10 = 11520 byte al secondo. L'Ethernet a 100 Mbps ha una velocità teorica di 100 / 8 = 12.5 MB al secondo, più di 1000 volte superiore. Il consumo medio è di 80 mA, ma l'alimentatore deve poter fornire almeno 500 mA per i picchi di corrente del Wi-Fi e dell'Ethernet. Una porta USB offre 500 mA, quindi è sufficiente.

Collegamento:

Alimentiamo il modulo dal pin +5V dell'adattatore CP2102, che trasferisce direttamente la tensione di 5 V dell'USB. Non usiamo il pin 3V3 dell'adattatore, perché il suo regolatore eroga una corrente bassa, insufficiente per un ESP32 con Wi-Fi. I segnali sono a 3.3 V, quindi non serve un convertitore di livello, ma non applicate mai 5 V sui pin di segnale. La linea seriale va incrociata: TXD dell'adattatore su RX0 e RXD dell'adattatore su TX0. Il pin IO0 va collegato a GND solo durante il caricamento del programma.

Pulsanti, regolazioni e indicatori:

La scheda non ha pulsanti, potenziometri, jumper o interruttori. L'avvio in modalità di programmazione si fa con un filo tra IO0 e GND, mentre il reset si fa con il pin EN. Lo stato della scheda è indicato da tre LED.

Modalità di programmazione. Collegate il filo tra IO0 e GND prima di alimentare la scheda o prima di resettarla. Quando Arduino IDE termina il caricamento, rimuovete il filo e riavviate l'alimentazione. Se il monitor seriale mostra il messaggio waiting for download, il filo è ancora inserito oppure la scheda non è stata riavviata.

Reset. Per riavviare il programma senza togliere l'alimentazione, toccate brevemente il pin EN a GND con un filo. Il programma riparte dall'inizio e rivedrete sul monitor seriale i messaggi di avvio.

LED POWER. Appena collegate l'adattatore alla USB il LED deve accendersi subito. È il primo segno che alimentazione e massa sono corrette.

Scheda e librerie:

In Arduino IDE selezionate da Tools > Board la scheda ESP32 Dev Module, dal pacchetto esp32 di Espressif Systems, installato da Boards Manager. Il pacchetto non è incluso in Arduino IDE, quindi aggiungete prima in File > Preferences, alla voce Additional boards manager URLs, l'indirizzo https://espressif.github.io/arduino-esp32/package_esp32_index.json. Il programma è stato scritto per le versioni 2.0.x e 3.x del pacchetto. Impostate Upload Speed a 115200.

Il programma usa solo le librerie incluse nel pacchetto ESP32 (WiFi.h, ETH.h e WiFiClient.h), quindi non è necessario installare alcuna libreria da Library Manager.

Il codice:

Il programma avvia l'interfaccia Ethernet con i parametri specifici della scheda WT32-ETH01, mostra gli eventi di rete e l'indirizzo IP, e ogni 5 secondi tenta una connessione TCP al gateway della rete, cioè al router, sulla porta 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");
  }
}

Come funziona il codice:

All'inizio definiamo i parametri del PHY: WT_PHY_ADDR è l'indirizzo 1 del circuito LAN8720A, WT_PHY_POWER è il pin 16 che avvia l'oscillatore, mentre WT_PHY_MDC e WT_PHY_MDIO sono i pin 23 e 18 del bus di gestione. La variabile ethConnected memorizza se abbiamo ricevuto un indirizzo IP, mentre lastCheck memorizza il momento dell'ultima verifica.

La funzione onEvent viene richiamata dal sistema a ogni evento di rete. Con ARDUINO_EVENT_ETH_START impostiamo il nome dell'host con ETH.setHostname. Con ARDUINO_EVENT_ETH_CONNECTED sappiamo che il cavo è collegato. Con ARDUINO_EVENT_ETH_GOT_IP mostriamo l'indirizzo IP, la maschera e il gateway e impostiamo ethConnected su true. Con ARDUINO_EVENT_ETH_DISCONNECTED impostiamo ethConnected su false.

Nel setup avviamo il monitor seriale a 115200 baud, registriamo la funzione onEvent con WiFi.onEvent e richiamiamo ETH.begin. L'ordine degli argomenti di ETH.begin è cambiato nella versione 3 del pacchetto ESP32, per questo la chiamata è scelta con la direttiva ESP_ARDUINO_VERSION_MAJOR.

Nel loop controlliamo ogni 5 secondi, con millis, se l'Ethernet è connesso. In caso affermativo mostriamo la velocità del collegamento con ETH.linkSpeed e la modalità duplex, poi creiamo un oggetto WiFiClient e chiamiamo client.connect verso ETH.gatewayIP() sulla porta 80, con un limite di 3000 ms. Se il router accetta la connessione, la rete funziona completamente e chiudiamo la connessione con client.stop.

Risultato:

Aprite il monitor seriale a 115200 baud dopo aver rimosso il collegamento IO0 - GND e riavviato la scheda. Dopo alcuni secondi compaiono i messaggi qui sotto, con l'indirizzo IP assegnato dal vostro 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

Problemi frequenti:

Il caricamento si interrompe con l'errore Failed to connect to ESP32. La causa è di solito IO0 non collegato a GND all'avvio oppure i fili TX e RX non incrociati. Collegate IO0 a GND, verificate che TXD dell'adattatore vada a RX0 e RXD a TX0, poi alimentate di nuovo la scheda e ripetete il caricamento.

Dopo il caricamento il monitor seriale mostra waiting for download. Il filo tra IO0 e GND è ancora inserito. Rimuovetelo e riavviate l'alimentazione.

Sul monitor seriale compaiono caratteri senza senso. La velocità del monitor seriale non è 115200 baud. Selezionate questa velocità nell'angolo in basso a destra del monitor.

Appare ETH started, ma non compare nessun indirizzo IP. Il cavo non è collegato, il router non ha il DHCP attivo oppure la porta è difettosa. Verificate il cavo, provate un'altra porta del router e controllate se appare il messaggio di cavo collegato.

Il modulo si riavvia da solo o si blocca all'avvio. L'alimentazione è insufficiente oppure la tensione sale troppo lentamente. Usate il pin +5V dell'adattatore o un alimentatore da 5 V con almeno 500 mA, evitate l'alimentazione dal pin 3V3 dell'adattatore e usate fili di alimentazione corti.

Il programma non compila e dà errore su ETH.begin. Il pacchetto ESP32 installato è una versione diversa da quella prevista. Usate una versione 2.0.x o 3.x e lasciate selezionata la scheda ESP32 Dev Module.

Limitazioni e consigli:

Il modulo ha una sola porta Ethernet da 10/100 Mbps, senza alimentazione tramite cavo di rete (PoE), quindi necessita sempre di un'alimentazione separata. I pin IO34 - IO39 sono solo ingressi e sui connettori a barra sono portati solo IO35, IO36 e IO39. Gli ingressi ADC2 (IO2, IO4, IO12, IO14, IO15) non possono essere letti mentre il Wi-Fi è attivo. I pin IO0, IO2 e IO12 sono pin di avvio e non devono essere forzati all'avvio.

Il livello logico è di 3.3 V, quindi per apparecchiature a 5 V aggiungete un convertitore di livello. Il modulo può lavorare tra -40 °C e +85 °C, ma è bene proteggerlo da umidità e vibrazioni.

In seguito potete costruire un gateway seriale-Ethernet con i pin TXD e RXD, un server web per comandare alcuni relè, un nodo MQTT per automazioni oppure un dispositivo con aggiornamento firmware OTA via rete.