Testar a conexão MQTT de um ESP32 passo a passo

Quando um ESP32 se recusa a falar com um broker MQTT, o monitor serial costuma mostrar uma única linha pouco útil: failed, rc=-2 try again in 5 seconds. O caminho mais rápido é testar a conexão camada por camada (Wi-Fi, DNS, porta TCP, handshake MQTT e publicação) e parar na primeira camada que falhar.

Este guia traz um sketch de diagnóstico para o core Arduino (core ESP32 3.x com PubSubClient 2.8) que faz exatamente isso, explica cada resultado e mostra como confirmar, do lado do broker, que a placa está realmente lá.

O checklist em resumo

Passo 1: tenha um log serial legível

Configure o monitor na mesma velocidade do Serial.begin(); 115200 é a convenção. No Arduino IDE, ajuste também Tools → Core Debug Level para Info ou Verbose: assim o core do ESP32 imprime eventos de Wi-Fi e erros de TLS que o seu sketch nunca vê. No PlatformIO, use monitor_speed = 115200 e build_flags = -DCORE_DEBUG_LEVEL=4.

Passos 2–6: o sketch de diagnóstico

Grave este sketch antes de mexer no seu firmware real. Ele verifica cada camada em ordem e imprime exatamente onde parou.

#include <WiFi.h>
#include <PubSubClient.h>

const char* WIFI_SSID = "your-ssid";
const char* WIFI_PASS = "your-wifi-password";
const char* MQTT_HOST = "broker.connectmq.com";
const uint16_t MQTT_PORT = 1883;
const char* MQTT_USER = "username";   // nullptr se o broker permitir acesso anônimo
const char* MQTT_PASS = "password";

WiFiClient net;
PubSubClient mqtt(net);
String clientId;

bool check() {
  Serial.println("\n[1] Wi-Fi");
  WiFi.mode(WIFI_STA);
  WiFi.begin(WIFI_SSID, WIFI_PASS);
  unsigned long t0 = millis();
  while (WiFi.status() != WL_CONNECTED && millis() - t0 < 20000) { delay(250); Serial.print('.'); }
  if (WiFi.status() != WL_CONNECTED) {
    Serial.printf("\nWi-Fi failed, status=%d\n", WiFi.status());
    return false;
  }
  Serial.printf("\nIP %s  gateway %s  RSSI %d dBm\n", WiFi.localIP().toString().c_str(),
                WiFi.gatewayIP().toString().c_str(), WiFi.RSSI());

  Serial.println("[2] DNS");
  IPAddress ip;
  if (!WiFi.hostByName(MQTT_HOST, ip)) { Serial.println("DNS lookup failed"); return false; }
  Serial.printf("%s -> %s\n", MQTT_HOST, ip.toString().c_str());

  Serial.println("[3] TCP port");
  if (!net.connect(ip, MQTT_PORT)) { Serial.println("TCP connect failed"); return false; }
  Serial.println("TCP OK");
  net.stop();

  Serial.println("[4] MQTT CONNECT");
  clientId = "esp32-" + WiFi.macAddress();
  clientId.replace(":", "");
  mqtt.setServer(MQTT_HOST, MQTT_PORT);
  mqtt.setBufferSize(1024);
  mqtt.setKeepAlive(30);
  if (!mqtt.connect(clientId.c_str(), MQTT_USER, MQTT_PASS)) {
    Serial.printf("MQTT failed, rc=%d\n", mqtt.state());
    return false;
  }
  Serial.printf("MQTT OK as %s\n", clientId.c_str());

  Serial.println("[5] PUBLISH");
  String topic = "testmqtt/esp32-check/" + clientId + "/hello";
  bool ok = mqtt.publish(topic.c_str(), "ESP32 connection test passed");
  Serial.printf("publish to %s: %s\n", topic.c_str(), ok ? "OK" : "FAILED");
  return ok;
}

void setup() {
  Serial.begin(115200);
  delay(1000);
  Serial.println(check() ? "\nALL CHECKS PASSED" : "\nCHECK FAILED - see the last step above");
}

void loop() {
  mqtt.loop();
}

Lendo os resultados

Códigos de status do Wi-Fi

Um bom RSSI fica mais ou menos entre -50 e -70 dBm. Se o Wi-Fi conecta, mas cai depois, veja desconexões de Wi-Fi e MQTT no ESP32.

DNS e TCP

DNS lookup failed significa que a placa não recebeu um servidor DNS utilizável do DHCP ou que o nome do host está errado. Verifique o mesmo nome a partir de um notebook na mesma rede com nslookup broker.connectmq.com. Como teste temporário você pode conectar pelo IP, mas não coloque isso em produção.

TCP connect failed (e rc=-2 no seu próprio firmware) significa que nada respondeu naquele host e porta. Causas comuns: rede de convidados ou firewall corporativo bloqueando a 1883, erro de digitação na porta ou uso da porta 8883 com um WiFiClient comum; portas TLS exigem WiFiClientSecure e um certificado de CA, como mostrado em MQTT sobre TLS no ESP32. Confirme a partir de um notebook no mesmo Wi-Fi com nc -vz broker.connectmq.com 1883.

Códigos de retorno do PubSubClient

Valores positivos são a resposta CONNACK do próprio broker, ou seja, a rede está ok e só resta a configuração. A referência de reason codes lista os códigos MQTT correspondentes, e PubSubClient não conecta aprofunda cada um deles.

publish() retorna false

O buffer padrão do PubSubClient tem 256 bytes e precisa comportar o pacote inteiro: cabeçalho, topic e payload. Um payload JSON de 200 bytes em um topic longo já passa disso, e publish() simplesmente retorna false sem nada chegar ao broker. Chame setBufferSize() antes de conectar; a calculadora de tamanho de pacote mostra o tamanho real de um pacote.

Passo 7: manter a conexão

mqtt.loop() precisa rodar com frequência, pelo menos várias vezes por intervalo de keep alive. Um delay(60000) no loop() ou uma leitura de sensor bloqueante garantem um rc=-3 depois de cerca de um período e meio de keep alive, porque o broker nunca recebe um PINGREQ. Troque delays longos por timers com millis() e reconecte com backoff em vez de travar em um loop while (!mqtt.connected()).

Confirme do lado do broker

Uma linha serial dizendo "OK" é a opinião do dispositivo. Verifique de forma independente: abra o cliente MQTT online, conecte-se ao mesmo broker e assine testmqtt/esp32-check/#. Reinicie a placa e a mensagem hello deve chegar em poucos segundos. No terminal, a mesma verificação é:

mosquitto_sub -h broker.connectmq.com -p 1883 \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/esp32-check/#' -v

Aguarde o seu ESP32 no navegador

A maioria dos problemas de MQTT no ESP32 nem são problemas de MQTT: são questões de Wi-Fi, DNS ou porta escondidas atrás de um único código de retorno. Teste uma camada por vez, leia o valor exato de status ou rc e confirme do lado do broker antes de passar para o seu firmware real. Para a configuração completa no Arduino, continue com MQTT no ESP32 com Arduino.

Perguntas frequentes