NodeMCU ESP8266: pines, Arduino IDE y servidor web Wi-Fi

El NodeMCU es una placa de desarrollo económica que combina el chip ESP8266 con Wi-Fi, una conexión USB, un regulador de 3,3 V y pines aptos para protoboard. Se programa con los mismos comandos que ya conoces del Arduino IDE y, por sí sola, puede conectarse a la red de tu casa y servir una página web que abres en el móvil. Si quieres llevar un sensor de temperatura a internet, activar un relé desde el teléfono o controlar una tira LED en casa, el NodeMCU ESP8266 es uno de los puntos de partida más baratos.

En esta guía verás paso a paso las características del NodeMCU, la confusa correspondencia entre D1–D8 y GPIO, qué pines afectan al arranque de la placa, la instalación en el Arduino IDE, la conexión al Wi-Fi y un servidor web que enciende un LED desde el móvil. En las últimas secciones encontrarás las diferencias entre el ESP8266 y el ESP32 y las soluciones a los errores más comunes.

¿Qué son el ESP8266 y el NodeMCU?

El ESP8266 es un microcontrolador de 32 bits con Wi-Fi integrado que Espressif lanzó en 2014. Gracias a su precio tan bajo, popularizó los proyectos Wi-Fi en el mundo maker. El nombre NodeMCU se refería al principio a un firmware basado en Lua escrito para este chip y a su placa de desarrollo de código abierto; hoy se usa como nombre genérico para las placas con el módulo ESP-12E. Casi nadie lo programa en Lua: lo habitual es usar el Arduino IDE o MicroPython.

En el mercado hay dos versiones habituales del NodeMCU. La V2 (Amica) es estrecha, usa un conversor USB-serie CP2102 y, al pincharla en la protoboard, deja una fila de agujeros libres a cada lado. La V3 (LoLin) es más ancha, usa un CH340G y tapa casi por completo una protoboard estándar, así que con la V3 es mucho más cómodo trabajar con dos protoboards una junto a otra. Ambas versiones tienen los mismos pines y ejecutan el mismo código. Si quieres una placa más pequeña, la Wemos D1 Mini lleva el mismo chip y funciona con los mismos programas.

Pines del NodeMCU: correspondencia entre D1–D8 y GPIO

Lo más confuso del NodeMCU es que las etiquetas D impresas en la placa no coinciden con los números GPIO reales del chip. Por ejemplo, el pin marcado como D1 es en realidad el GPIO 5. Si eliges la placa NodeMCU en el Arduino IDE puedes escribir D1 en el código y el compilador lo convierte en 5 automáticamente; pero si escribes digitalWrite(1, HIGH), estarás controlando el GPIO 1, que es el pin TX del puerto serie. En MicroPython siempre se usa el número GPIO.

Según esta tabla, los pines que puedes usar sin preocupaciones en tus primeros proyectos son D1, D2, D5, D6 y D7. D3, D4 y D8, en cambio, deciden el modo de arranque: al recibir alimentación, el ESP8266 mira los niveles de GPIO 0, GPIO 2 y GPIO 15 y, para un arranque normal, espera GPIO 0 y GPIO 2 en HIGH y GPIO 15 en LOW. Si un pulsador, relé o sensor conectado a estos pines cambia el nivel durante el arranque, la placa arranca en modo de carga en lugar de ejecutar tu programa, o no arranca. Aun así, D3 y D4 sirven para pulsadores, porque un pulsador no está pulsado al arrancar; pero mantén lejos de estos pines los módulos cuya salida esté en LOW.

El pin A0 también es un caso especial: la entrada analógica del chip ESP8266 solo mide de 0 a 1 V, pero gracias al divisor de tensión de 220 kΩ y 100 kΩ de la placa NodeMCU puedes aplicar a A0 unos 0–3,2 V, y analogRead(A0) devuelve ese rango como 0–1023. Como solo hay una entrada analógica, si vas a usar varios sensores analógicos necesitarás un ADC I2C como el ADS1115. Los pines D1 y D2 forman el bus I2C por defecto; tienes lo básico de I2C en ¿Qué es I2C?.

Instalar el ESP8266 en el Arduino IDE

1. En el Arduino IDE abre Archivo > Preferencias y añade https://arduino.esp8266.com/stable/package_esp8266com_index.json en el campo «URLs adicionales de gestor de placas».
2. Abre Herramientas > Placa > Gestor de placas, busca esp8266 e instala el paquete de ESP8266 Community.
3. En el menú Herramientas > Placa elige NodeMCU 1.0 (ESP-12E Module). Si usas una Wemos D1 Mini, elige LOLIN(WEMOS) D1 R2 & mini.
4. Conecta la placa con un cable de datos y elige su puerto en Herramientas > Puerto. Si no aparece ningún puerto, instala el driver CH340 para las placas V3 o el CP2102 para las V2.
5. Deja Upload Speed en 115200; cuando la carga funcione sin fallos, puedes subirla a 921600 para cargar más rápido.

Primer programa: hacer parpadear el LED integrado

En el NodeMCU hay un LED azul en el módulo ESP-12E conectado al GPIO 2 (D4); las placas V2 (Amica) tienen un segundo LED en D0. Estos LED funcionan con lógica invertida: se encienden cuando el pin está en LOW y se apagan en HIGH. En el núcleo de Arduino, la constante LED_BUILTIN ya está definida como 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}

Conectarse al Wi-Fi

El verdadero punto fuerte del ESP8266 es el Wi-Fi. El programa siguiente conecta la placa a la red de tu casa en modo estación y muestra en el monitor serie la dirección IP asignada por el router y la intensidad de la señal. Si no logra conectarse en 20 segundos, deja de esperar y muestra un aviso. Cambia el nombre de la red y la contraseña por los tuyos y abre el monitor serie a 115200 baudios:

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}

Controlar un LED desde el móvil: un servidor web sencillo

Ahora vamos a convertir el NodeMCU en un pequeño servidor web. Conecta un LED al pin D1 (GPIO 5) con una resistencia de 220 Ω: la pata larga del LED va a D1 a través de la resistencia y la corta a GND. Con un LED rojo, esta resistencia da una corriente de (3,3 V − 2 V) / 220 Ω ≈ 6 mA, muy por debajo del límite del pin; para calcular el valor de tu propio LED usa la Calculadora de resistencia para LED. Después de cargar el código, abre la dirección que aparece en el monitor serie en el navegador de un móvil conectado al mismo 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}

Si la página no se abre, asegúrate de que el móvil está conectado a la misma red Wi-Fi que el NodeMCU y no a una red de invitados o a los datos móviles. El nombre nodemcu.local suele funcionar en ordenadores y iPhone; algunos móviles Android no admiten mDNS, así que en ellos tendrás que usar la dirección IP. Si en lugar del LED conectas un módulo relé, el mismo código te permite controlar una lámpara real; tienes los detalles en ¿Qué es un módulo relé?.

Modo punto de acceso (AP): conexión sin router

Si no hay Wi-Fi cerca, el NodeMCU puede crear su propia red. En modo punto de acceso conectas el móvil directamente a la red NodeMCU-AP y la placa suele responder en 192.168.4.1. Este modo es ideal para un sistema de riego en el jardín o un aparato de medida que se usa en el exterior. Para combinar el servidor web anterior con este modo, basta con usar las líneas de softAP en lugar de las de WiFi.begin; el modo WIFI_AP_STA cumple los dos papeles a la vez. La contraseña debe tener al menos 8 caracteres o la red no se creará.

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

Además del lenguaje de Arduino, el NodeMCU también se puede programar con MicroPython. Después de grabar el firmware de MicroPython en la placa con esptool, ejecutas código Python directamente desde un editor como Thonny. Como la memoria del ESP8266 es limitada, los programas grandes de MicroPython pueden dar errores de memoria, pero para proyectos sencillos de Wi-Fi y sensores resulta muy práctico. Ten en cuenta que en MicroPython el número de pin es el GPIO, no la etiqueta 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?

En resumen, el ESP8266 sigue siendo más que suficiente para enviar a internet los datos de un sensor, activar un relé desde el móvil o servir una página web sencilla, y además es más barato. Para proyectos nuevos que necesiten Bluetooth, muchas entradas analógicas, cámara, mucha potencia de cálculo o varias tareas a la vez, el ESP32 es mejor opción. El código se adapta fácilmente: muchas veces basta con escribir WiFi.h en lugar de ESP8266WiFi.h, WebServer.h en lugar de ESP8266WebServer.h y ESPmDNS.h en lugar de ESP8266mDNS.h, borrar la línea MDNS.update() (el ESP32 no la tiene) y usar los números GPIO en lugar de etiquetas de placa como D1. Más detalles en ¿Qué es el ESP32? y ¿Arduino o ESP32?.

Alimentación y sueño profundo

El NodeMCU se alimenta con 5 V por USB o por el pin VIN, y el regulador de la placa los baja a 3,3 V. El pico de 170 mA al transmitir por Wi-Fi puede provocar una caída de tensión en un puerto USB débil o con un cable fino y hacer que la placa se reinicie sola, así que usa un buen cable y un adaptador de al menos 1 A. En proyectos con batería, ESP.deepSleep() duerme el chip con unos 20 µA; para que pueda despertar al terminar el temporizador, tienes que unir el pin D0 (GPIO 16) con el pin RST. Sin embargo, el conversor USB-serie y el regulador de la placa siguen consumiendo mientras duerme, por eso para una larga duración de batería dan mejor resultado un módulo ESP-12 suelto o placas de bajo consumo. Para estimar la duración de la batería usa la Calculadora de autonomía de batería.

Ideas de proyectos con el NodeMCU

• Termómetro Wi-Fi: Muestra la temperatura y la humedad medidas por un DHT11 en una página que abres en el móvil.
• Enchufe inteligente: Enciende y apaga una lámpara con un módulo relé y un botón en una página web.
• Aviso de riego: Conecta un sensor de humedad del suelo a A0 y muestra un aviso en la página cuando la tierra se seque.
• Tira LED Wi-Fi: Elige desde el móvil el color y el efecto de una tira WS2812B.
• Reloj por internet: Obtén la hora de un servidor NTP y muéstrala en una pantalla LCD I2C.
• Alarma de movimiento: Envía un mensaje de Telegram cuando un sensor PIR detecte movimiento.

Errores frecuentes y cómo solucionarlos

El NodeMCU ESP8266 es la forma más económica de llevar lo que has aprendido con Arduino al mundo inalámbrico: con unas pocas líneas de código se conecta a la red de tu casa y te permite crear aparatos que controlas desde el móvil. En la aplicación BlueGrays encontrarás proyectos inalámbricos en el ESP32, como conexión Wi-Fi, servidor web, WebSocket, reloj NTP y mDNS, con esquemas de circuito y código paso a paso, y podrás adaptar fácilmente la misma lógica a tu NodeMCU.