Guia do NodeMCU ESP8266: pinagem, configuração na Arduino IDE e servidor web

O NodeMCU é uma placa de desenvolvimento acessível que junta o chip ESP8266, com Wi-Fi, a uma conexão USB, um regulador de 3,3 V e pinos que encaixam bem na protoboard. Você o programa com os mesmos comandos que já conhece da Arduino IDE e, sozinho, ele consegue entrar na rede da sua casa e servir uma página web que você abre no celular. Se você quer colocar um sensor de temperatura na internet, ligar um relé pelo celular ou controlar uma fita de LED em casa, o NodeMCU ESP8266 é um dos pontos de partida mais baratos.

Neste guia você vai ver passo a passo as especificações do NodeMCU, a confusa correspondência entre os pinos D1–D8 e os GPIOs, quais pinos afetam a inicialização da placa, a configuração na Arduino IDE, a conexão ao Wi-Fi e um servidor web que liga um LED pelo celular. Nas últimas seções você encontra as diferenças entre o ESP8266 e o ESP32 e soluções para os erros mais comuns.

O que são o ESP8266 e o NodeMCU?

O ESP8266 é um microcontrolador de 32 bits com Wi-Fi embutido que a Espressif lançou em 2014. Graças ao preço muito baixo, ele popularizou os projetos com Wi-Fi no mundo maker. O nome NodeMCU se referia originalmente a um firmware baseado em Lua escrito para esse chip e à sua placa de desenvolvimento de código aberto; hoje é usado como nome genérico para placas construídas em torno do módulo ESP-12E. Mas você raramente vai programá-lo em Lua; a maioria das pessoas usa a Arduino IDE ou o MicroPython.

Há duas versões comuns do NodeMCU no mercado. A V2 (Amica) é estreita, usa um chip USB-serial CP2102 e deixa uma fileira de furos livres de cada lado quando encaixada na protoboard. A V3 (LoLin) é mais larga, usa um chip CH340G e cobre quase toda uma protoboard comum, então colocar duas protoboards lado a lado facilita muito o trabalho com uma V3. As duas versões têm a mesma pinagem e rodam o mesmo código. Se você quer uma placa menor, a Wemos D1 Mini traz o mesmo chip e roda os mesmos sketches.

Pinagem do NodeMCU: correspondência entre D1–D8 e os GPIOs

O mais confuso no NodeMCU é que as marcações D impressas na placa não são os números GPIO reais do chip. Por exemplo, o pino marcado D1 é na verdade o GPIO 5. Quando você seleciona a placa NodeMCU na Arduino IDE, pode escrever D1 no código e o compilador o transforma em 5 automaticamente; mas, se você escrever digitalWrite(1, HIGH), estará acionando o GPIO 1, que é o pino TX da porta serial. No MicroPython você sempre usa o número do GPIO.

Pela tabela, os pinos que você pode usar sem preocupação nos primeiros projetos são D1, D2, D5, D6 e D7. D3, D4 e D8 são os pinos que definem o modo de inicialização da placa: quando recebe alimentação, o ESP8266 confere os níveis do GPIO 0, do GPIO 2 e do GPIO 15 e, para uma inicialização normal, espera que o GPIO 0 e o GPIO 2 estejam em HIGH e o GPIO 15 em LOW. Se um botão, relé ou sensor ligado a esses pinos muda o nível na partida, a placa entra no modo de carregamento em vez de rodar o seu programa, ou nem inicia. D3 e D4 ainda podem ser usados para botões, porque o botão não está apertado na inicialização, mas mantenha longe desses pinos os módulos cuja saída fica em LOW.

O pino A0 também é um caso especial: a entrada analógica do chip ESP8266 só mede 0–1 V, mas, graças ao divisor de tensão de 220 kΩ e 100 kΩ na placa NodeMCU, você pode colocar cerca de 0–3,2 V no A0, e o analogRead(A0) retorna essa faixa como 0–1023. Como só há uma entrada analógica, você vai precisar de um ADC I2C como o ADS1115 se quiser usar vários sensores analógicos. Os pinos D1 e D2 são o barramento I2C padrão; o básico do I2C está em O que é I2C?.

Configurando o ESP8266 na Arduino IDE

1. Na Arduino IDE, abra Arquivo > Preferências e adicione https://arduino.esp8266.com/stable/package_esp8266com_index.json no campo “URLs do Gerenciador de Placas Adicionais”.
2. Abra Ferramentas > Placa > Gerenciador de Placas, busque esp8266 e instale o pacote ESP8266 Community.
3. No menu Ferramentas > Placa, selecione NodeMCU 1.0 (ESP-12E Module). Se você usa uma Wemos D1 Mini, escolha LOLIN(WEMOS) D1 R2 & mini.
4. Conecte a placa com um cabo de dados e selecione a porta em Ferramentas > Porta. Se nenhuma porta aparecer, instale o driver CH340 para placas V3 ou o driver CP2102 para placas V2.
5. Deixe o Upload Speed em 115200; quando os carregamentos estiverem funcionando bem, você pode subir para 921600 para acelerá-los.

Primeiro sketch: piscando o LED da placa

No NodeMCU há um LED azul no módulo ESP-12E ligado ao GPIO 2 (D4); as placas V2 (Amica) têm um segundo LED no D0. Esses LEDs usam lógica invertida: acendem quando o pino está em LOW e apagam quando está em HIGH. No core Arduino, a constante LED_BUILTIN já vem 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}

Conectando ao Wi-Fi

O Wi-Fi é o ponto forte do ESP8266. O sketch abaixo conecta a placa à rede da sua casa no modo estação e mostra no Monitor Serial o endereço IP dado pelo roteador e a intensidade do sinal. Se não conseguir conectar em 20 segundos, ele para de esperar e mostra um aviso. Troque o nome da rede e a senha pelos seus e abra o Monitor Serial em 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}

Controlando um LED pelo celular: um servidor web simples

Agora vamos transformar o NodeMCU em um pequeno servidor web. Ligue um LED ao pino D1 (GPIO 5) por um resistor de 220 Ω: a perna longa do LED vai ao D1 pelo resistor, e a perna curta vai ao GND. Para um LED vermelho, esse resistor dá uma corrente de (3,3 V − 2 V) / 220 Ω ≈ 6 mA, bem abaixo do limite do pino; para calcular o valor para o seu LED, use a calculadora de resistor para LED. Depois de carregar, abra o endereço mostrado no Monitor Serial no navegador de um celular conectado ao mesmo 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 a página não abrir, confira se o celular está conectado à mesma rede Wi-Fi que o NodeMCU, e não a uma rede de visitantes ou aos dados móveis. O nome nodemcu.local costuma funcionar em computadores e iPhones; alguns celulares Android não têm suporte a mDNS, e aí você vai precisar do endereço IP. Se você ligar um módulo relé no lugar do LED, o mesmo código permite controlar uma lâmpada de verdade; veja os detalhes em O que é módulo relé?.

Modo ponto de acesso (AP): conectando sem roteador

Se não houver Wi-Fi por perto, o NodeMCU pode criar a própria rede. No modo ponto de acesso, você conecta o celular direto à rede NodeMCU-AP, e a placa costuma responder em 192.168.4.1. Esse modo é ideal para um sistema de rega no jardim ou um aparelho de medição usado em campo. Para juntar o servidor web acima com esse modo, basta usar as linhas softAP no lugar das linhas WiFi.begin; o modo WIFI_AP_STA assume os dois papéis ao mesmo tempo. A senha precisa ter pelo menos 8 caracteres, senão a rede não é criada.

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 com MicroPython

Além da linguagem do Arduino, o NodeMCU também pode ser programado em MicroPython. Depois de gravar o firmware do MicroPython na placa com o esptool, você roda código Python direto de um editor como o Thonny. Como a memória do ESP8266 é limitada, você pode esbarrar em erros de memória com programas grandes em MicroPython, mas para projetos simples de Wi-Fi e sensores ele é muito prático. Repare que no MicroPython você escreve como número do pino o número do GPIO, e não a marcação 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 ou ESP32?

Resumindo: o ESP8266 ainda dá conta de sobra de tarefas como enviar os dados de um sensor para a internet, ligar um relé pelo celular ou servir uma página web simples, e é mais barato. Para projetos novos que precisam de Bluetooth, muitas entradas analógicas, câmera, processamento rápido ou muitas tarefas ao mesmo tempo, o ESP32 é a melhor escolha. O código migra com facilidade: trocar ESP8266WiFi.h por WiFi.h, ESP8266WebServer.h por WebServer.h e ESP8266mDNS.h por ESPmDNS.h, apagar a linha MDNS.update() (o ESP32 não tem) e usar números de GPIO em vez de marcações da placa como D1 muitas vezes é tudo o que precisa. Para mais detalhes, veja O que é ESP32? e Arduino ou ESP32?.

Alimentação e deep sleep

O NodeMCU é alimentado com 5 V pela USB ou pelo pino VIN, e o regulador da placa baixa para 3,3 V. O pico de corrente de 170 mA durante a transmissão Wi-Fi pode causar uma queda de tensão em uma porta USB fraca ou em um cabo fino e fazer a placa reiniciar sozinha, então use um bom cabo e uma fonte que forneça pelo menos 1 A. Em projetos com bateria, o ESP.deepSleep() coloca o chip para dormir com cerca de 20 µA; para que ele acorde quando o timer acabar, você precisa ligar o pino D0 (GPIO 16) ao pino RST. Mas o chip USB-serial e o regulador da placa continuam puxando corrente enquanto ele dorme, então, para uma bateria de longa duração, um módulo ESP-12 avulso ou uma placa de baixo consumo dá resultados melhores. Para estimar a duração da bateria, use a calculadora de duração da bateria.

Ideias de projetos com o NodeMCU

• Termômetro Wi-Fi: mostre a temperatura e a umidade medidas por um DHT11 em uma página que você abre no celular.
• Tomada inteligente: ligue e desligue uma lâmpada com um módulo relé e um botão em uma página web.
• Alerta de rega de plantas: ligue um sensor de umidade do solo no A0 e mostre um aviso na página quando a terra secar.
• Fita de LED via Wi-Fi: escolha pelo celular a cor e o efeito de uma fita WS2812B.
• Relógio pela internet: pegue a hora de um servidor NTP e mostre em um display LCD I2C.
• Alarme de movimento: envie uma mensagem no Telegram quando um sensor PIR detectar movimento.

Erros comuns e como corrigir

O NodeMCU ESP8266 é o jeito mais acessível de levar o que você aprendeu com o Arduino para o mundo sem fio: com poucas linhas de código ele entra na rede da sua casa e permite montar aparelhos que você controla pelo celular. No app BlueGrays você encontra projetos sem fio como conexão Wi-Fi, servidor web, WebSocket, relógio NTP e mDNS no ESP32, com esquemas do circuito e código passo a passo, e pode adaptar facilmente a mesma lógica ao seu NodeMCU.