NodeMCU ESP8266: pinout, Arduino IDE e web server Wi-Fi

Il NodeMCU è una scheda di sviluppo economica che unisce il chip ESP8266 con Wi-Fi a una connessione USB, un regolatore a 3,3 V e pin adatti alla breadboard. Si programma con gli stessi comandi che conosci già dall'Arduino IDE e, da sola, può collegarsi alla rete di casa e offrire una pagina web da aprire sul telefono. Se vuoi portare online un sensore di temperatura, azionare un relè dal telefono o controllare una striscia LED in casa, il NodeMCU ESP8266 è uno dei punti di partenza più economici.

In questa guida vedrai passo dopo passo le caratteristiche del NodeMCU, la confusa corrispondenza tra D1–D8 e GPIO, quali pin influenzano l'avvio della scheda, l'installazione nell'Arduino IDE, la connessione al Wi-Fi e un web server che accende un LED dal telefono. Nelle ultime sezioni troverai le differenze tra ESP8266 ed ESP32 e le soluzioni agli errori più comuni.

Cosa sono l'ESP8266 e il NodeMCU?

L'ESP8266 è un microcontrollore a 32 bit con Wi-Fi integrato lanciato da Espressif nel 2014. Grazie al prezzo bassissimo ha reso popolari i progetti Wi-Fi nel mondo maker. Il nome NodeMCU indicava in origine un firmware basato su Lua scritto per questo chip e la relativa scheda di sviluppo open source; oggi è usato come nome generico per le schede con modulo ESP-12E. Quasi nessuno lo programma più in Lua: di solito si usano l'Arduino IDE o MicroPython.

In commercio ci sono due versioni comuni del NodeMCU. La V2 (Amica) è stretta, usa un convertitore USB-seriale CP2102 e, inserita nella breadboard, lascia libera una fila di fori su ogni lato. La V3 (LoLin) è più larga, usa un CH340G e copre quasi del tutto una breadboard standard, quindi con la V3 è molto più comodo lavorare con due breadboard affiancate. Entrambe le versioni hanno lo stesso pinout ed eseguono lo stesso codice. Se vuoi una scheda più piccola, la Wemos D1 Mini monta lo stesso chip e funziona con gli stessi sketch.

Pinout del NodeMCU: corrispondenza tra D1–D8 e GPIO

La cosa più confusa del NodeMCU è che le etichette D stampate sulla scheda non corrispondono ai veri numeri GPIO del chip. Per esempio, il pin con la scritta D1 è in realtà il GPIO 5. Se nell'Arduino IDE scegli la scheda NodeMCU, puoi scrivere D1 nel codice e il compilatore lo trasforma automaticamente in 5; ma se scrivi digitalWrite(1, HIGH), stai comandando il GPIO 1, cioè il pin TX della porta seriale. In MicroPython si usa sempre il numero GPIO.

Secondo questa tabella, i pin che puoi usare senza pensieri nei primi progetti sono D1, D2, D5, D6 e D7. D3, D4 e D8, invece, determinano la modalità di avvio: quando arriva l'alimentazione, l'ESP8266 controlla i livelli di GPIO 0, GPIO 2 e GPIO 15 e, per un avvio normale, si aspetta GPIO 0 e GPIO 2 a HIGH e GPIO 15 a LOW. Se un pulsante, un relè o un sensore collegato a questi pin cambia il livello all'avvio, la scheda parte in modalità caricamento invece di eseguire il tuo programma, oppure non parte affatto. D3 e D4 si possono comunque usare per i pulsanti, perché all'avvio un pulsante non è premuto; tieni invece lontani da questi pin i moduli con l'uscita a LOW.

Anche il pin A0 è un caso particolare: l'ingresso analogico del chip ESP8266 misura solo 0–1 V, ma grazie al partitore da 220 kΩ e 100 kΩ presente sulla scheda NodeMCU puoi applicare ad A0 circa 0–3,2 V, e analogRead(A0) restituisce questo intervallo come 0–1023. Avendo un solo ingresso analogico, per usare più sensori analogici ti serve un ADC I2C come l'ADS1115. I pin D1 e D2 sono il bus I2C predefinito; le basi dell'I2C le trovi in Cos'è l'I2C?.

Installare l'ESP8266 nell'Arduino IDE

1. Nell'Arduino IDE apri File > Impostazioni e aggiungi https://arduino.esp8266.com/stable/package_esp8266com_index.json nel campo «URL aggiuntive per il gestore schede».
2. Apri Strumenti > Scheda > Gestore schede, cerca esp8266 e installa il pacchetto ESP8266 Community.
3. Nel menu Strumenti > Scheda scegli NodeMCU 1.0 (ESP-12E Module). Se usi una Wemos D1 Mini, scegli invece LOLIN(WEMOS) D1 R2 & mini.
4. Collega la scheda con un cavo dati e seleziona la porta in Strumenti > Porta. Se non compare nessuna porta, installa il driver CH340 per le schede V3 o il CP2102 per le V2.
5. Lascia Upload Speed a 115200; quando il caricamento funziona senza problemi, puoi alzarla a 921600 per caricare più in fretta.

Primo sketch: far lampeggiare il LED integrato

Sul NodeMCU il modulo ESP-12E ha un LED blu collegato al GPIO 2 (D4); le schede V2 (Amica) hanno un secondo LED su D0. Questi LED funzionano con logica invertita: si accendono quando il pin è LOW e si spengono quando è HIGH. Nel core Arduino la costante LED_BUILTIN è già definita come 2:

1// NodeMCU dahili LED'i: GPIO2 (D4), ters mantık / onboard LED: GPIO2 (D4), inverted logic
2
3void setup() {
4  pinMode(LED_BUILTIN, OUTPUT);
5}
6
7void loop() {
8  digitalWrite(LED_BUILTIN, LOW);    // LOW = yanar / LOW = on
9  delay(500);
10  digitalWrite(LED_BUILTIN, HIGH);   // HIGH = söner / HIGH = off
11  delay(500);
12}

Connettersi al Wi-Fi

Il vero punto di forza dell'ESP8266 è il Wi-Fi. Lo sketch seguente collega la scheda alla rete di casa in modalità station e scrive nel monitor seriale l'indirizzo IP assegnato dal router e l'intensità del segnale. Se non riesce a connettersi entro 20 secondi smette di aspettare e mostra un avviso. Sostituisci nome della rete e password con i tuoi e apri il monitor seriale a 115200 baud:

1#include <ESP8266WiFi.h>
2
3const char* ssid = "AgAdi";          // Wi-Fi adın / your Wi-Fi name
4const char* password = "Sifre123";   // Wi-Fi şifren / your Wi-Fi password
5
6void setup() {
7  Serial.begin(115200);
8  Serial.println();
9  WiFi.mode(WIFI_STA);               // istemci modu / station mode
10  WiFi.begin(ssid, password);
11  Serial.print("Baglaniyor / connecting");
12  unsigned long start = millis();
13  while (WiFi.status() != WL_CONNECTED) {
14    delay(500);
15    Serial.print('.');
16    if (millis() - start > 20000) {  // 20 sn'de bağlanamazsa / give up after 20 s
17      Serial.println("\nBaglanamadi, ag adini ve sifreyi kontrol et / failed, check SSID and password");
18      return;
19    }
20  }
21  Serial.println();
22  Serial.print("IP: ");
23  Serial.println(WiFi.localIP());    // modemin verdiği adres / address given by the router
24  Serial.print("Sinyal / RSSI: ");
25  Serial.print(WiFi.RSSI());         // -50 iyi, -80 zayıf / -50 good, -80 weak
26  Serial.println(" dBm");
27}
28
29void loop() {
30}

Controllare un LED dal telefono: un semplice web server

Ora trasformiamo il NodeMCU in un piccolo web server. Collega un LED al pin D1 (GPIO 5) con una resistenza da 220 Ω: la gamba lunga del LED va a D1 attraverso la resistenza, quella corta a GND. Con un LED rosso questa resistenza dà una corrente di (3,3 V − 2 V) / 220 Ω ≈ 6 mA, ben sotto il limite del pin; per calcolare il valore adatto al tuo LED usa il Calcolatore resistenza LED. Dopo il caricamento apri l'indirizzo mostrato nel monitor seriale nel browser di un telefono collegato allo stesso Wi-Fi.

1#include <ESP8266WiFi.h>
2#include <ESP8266WebServer.h>
3#include <ESP8266mDNS.h>
4
5const char* ssid = "AgAdi";          // Wi-Fi adın / your Wi-Fi name
6const char* password = "Sifre123";   // Wi-Fi şifren / your Wi-Fi password
7
8const int LED_PIN = D1;              // GPIO5, 220 ohm direnç ile LED / LED through a 220 ohm resistor
9bool ledOn = false;
10
11ESP8266WebServer server(80);
12
13void handleRoot() {
14  String html = "<!DOCTYPE html><html><head><meta charset='utf-8'>"
15                "<meta name='viewport' content='width=device-width,initial-scale=1'>"
16                "<title>NodeMCU</title></head>"
17                "<body style='font-family:sans-serif;text-align:center'>"
18                "<h1>NodeMCU LED</h1><p>LED: <b>";
19  html += ledOn ? "ACIK / ON" : "KAPALI / OFF";
20  html += "</b></p><p>A0: ";
21  html += analogRead(A0);            // 0-1023 arası analog değer / analog value 0-1023
22  html += "</p><p><a href='/on'><button>AC / ON</button></a> "
23          "<a href='/off'><button>KAPAT / OFF</button></a></p></body></html>";
24  server.send(200, "text/html", html);
25}
26
27void setLed(bool on) {
28  ledOn = on;
29  digitalWrite(LED_PIN, on ? HIGH : LOW);
30  server.sendHeader("Location", "/");   // ana sayfaya yönlendir / redirect to the main page
31  server.send(303, "text/plain", "");
32}
33
34void setup() {
35  pinMode(LED_PIN, OUTPUT);
36  digitalWrite(LED_PIN, LOW);
37  Serial.begin(115200);
38  WiFi.mode(WIFI_STA);
39  WiFi.begin(ssid, password);
40  while (WiFi.status() != WL_CONNECTED) {
41    delay(500);
42    Serial.print('.');
43  }
44  Serial.println();
45  Serial.print("Tarayicida ac / open in browser: http://");
46  Serial.println(WiFi.localIP());
47
48  if (MDNS.begin("nodemcu")) {       // http://nodemcu.local adresi / address http://nodemcu.local
49    MDNS.addService("http", "tcp", 80);
50  }
51
52  server.on("/", handleRoot);
53  server.on("/on", []() { setLed(true); });
54  server.on("/off", []() { setLed(false); });
55  server.onNotFound([]() { server.send(404, "text/plain", "Bulunamadi / not found"); });
56  server.begin();
57}
58
59void loop() {
60  server.handleClient();             // gelen istekleri işle / handle incoming requests
61  MDNS.update();
62}

Se la pagina non si apre, assicurati che il telefono sia collegato alla stessa rete Wi-Fi del NodeMCU e non a una rete ospiti o ai dati mobili. Il nome nodemcu.local di solito funziona su computer e iPhone; alcuni telefoni Android non supportano mDNS, quindi lì dovrai usare l'indirizzo IP. Se al posto del LED colleghi un modulo relè, con lo stesso codice puoi comandare una vera lampada; trovi i dettagli in Cos'è un modulo relè?.

Modalità access point (AP): connessione senza router

Se nei dintorni non c'è Wi-Fi, il NodeMCU può creare una propria rete. In modalità access point colleghi il telefono direttamente alla rete NodeMCU-AP e la scheda risponde di solito all'indirizzo 192.168.4.1. Questa modalità è ideale per un impianto di irrigazione in giardino o uno strumento di misura usato all'aperto. Per unire il web server visto sopra a questa modalità basta usare le righe softAP al posto delle righe WiFi.begin; la modalità WIFI_AP_STA svolge entrambi i ruoli contemporaneamente. La password deve avere almeno 8 caratteri, altrimenti la rete non viene creata.

1#include <ESP8266WiFi.h>
2
3void setup() {
4  Serial.begin(115200);
5  WiFi.mode(WIFI_AP);                            // kendi ağını kur / create its own network
6  bool ok = WiFi.softAP("NodeMCU-AP", "12345678"); // ad ve en az 8 karakter şifre / name and 8+ char password
7  Serial.println(ok ? "AP hazir / AP ready" : "AP hatasi / AP error");
8  Serial.print("IP: ");
9  Serial.println(WiFi.softAPIP());               // genellikle 192.168.4.1 / usually 192.168.4.1
10}
11
12void loop() {
13  Serial.print("Bagli cihaz / stations: ");
14  Serial.println(WiFi.softAPgetStationNum());
15  delay(3000);
16}

ESP8266 con MicroPython

Oltre che con il linguaggio Arduino, il NodeMCU si può programmare anche in MicroPython. Dopo aver caricato il firmware MicroPython sulla scheda con esptool, esegui il codice Python direttamente da un editor come Thonny. Dato che la memoria dell'ESP8266 è limitata, i programmi MicroPython più grandi possono dare errori di memoria, ma per semplici progetti Wi-Fi e con sensori è molto pratico. Ricorda che in MicroPython il numero del pin è il GPIO, non l'etichetta D:

1import network, time
2from machine import Pin
3
4led = Pin(2, Pin.OUT)                     # D4 = GPIO2, dahili LED / onboard LED
5wlan = network.WLAN(network.STA_IF)
6wlan.active(True)
7wlan.connect("AgAdi", "Sifre123")         # Wi-Fi adı ve şifresi / Wi-Fi name and password
8
9while not wlan.isconnected():
10    time.sleep(0.5)
11print("IP:", wlan.ifconfig()[0])
12
13while True:
14    led.value(not led.value())            # ters mantık: 0 = yanar / inverted: 0 = on
15    time.sleep(0.5)

ESP8266 o ESP32?

In sintesi, l'ESP8266 è ancora più che sufficiente per inviare in rete i dati di un sensore, azionare un relè dal telefono o servire una semplice pagina web, e costa meno. Per i nuovi progetti che richiedono Bluetooth, molti ingressi analogici, una fotocamera, molta potenza di calcolo o più attività contemporanee, l'ESP32 è la scelta migliore. Il codice si porta facilmente: spesso basta scrivere WiFi.h al posto di ESP8266WiFi.h, WebServer.h al posto di ESP8266WebServer.h ed ESPmDNS.h al posto di ESP8266mDNS.h, cancellare la riga MDNS.update() (sull'ESP32 non esiste) e usare i numeri GPIO invece delle etichette della scheda come D1. Per i dettagli leggi Cos'è l'ESP32? e Arduino o ESP32?.

Alimentazione e deep sleep

Il NodeMCU si alimenta a 5 V tramite USB o il pin VIN, e il regolatore sulla scheda porta la tensione a 3,3 V. Il picco di 170 mA durante la trasmissione Wi-Fi può far calare la tensione su una porta USB debole o con un cavo sottile e far riavviare la scheda da sola; usa quindi un buon cavo e un alimentatore da almeno 1 A. Nei progetti a batteria, ESP.deepSleep() mette il chip a dormire con circa 20 µA; perché possa risvegliarsi allo scadere del timer, devi collegare il pin D0 (GPIO 16) al pin RST. Il convertitore USB-seriale e il regolatore della scheda però continuano a consumare anche durante il sonno, per cui per una lunga autonomia danno risultati migliori un modulo ESP-12 nudo o schede a basso consumo. Per stimare la durata della batteria usa il Calcolatore durata batteria.

Idee di progetti con il NodeMCU

• Termometro Wi-Fi: Mostra temperatura e umidità misurate da un DHT11 su una pagina da aprire sul telefono.
• Presa smart: Accendi e spegni una lampada con un modulo relè e un pulsante su una pagina web.
• Avviso irrigazione: Collega un sensore di umidità del terreno ad A0 e mostra un avviso sulla pagina quando il terreno si secca.
• Striscia LED Wi-Fi: Scegli dal telefono colore ed effetto di una striscia WS2812B.
• Orologio internet: Prendi l'ora da un server NTP e mostrala su un display LCD I2C.
• Allarme di movimento: Invia un messaggio Telegram quando un sensore PIR rileva un movimento.

Errori comuni e soluzioni

Il NodeMCU ESP8266 è il modo più economico per portare ciò che hai imparato con Arduino nel mondo wireless: con poche righe di codice si collega alla rete di casa e ti permette di creare dispositivi da comandare con il telefono. Nell'app BlueGrays trovi progetti wireless su ESP32, come connessione Wi-Fi, web server, WebSocket, orologio NTP e mDNS, con schemi elettrici e codice passo dopo passo, e puoi adattare facilmente la stessa logica al tuo NodeMCU.