MQTT explicado fácil: instala Mosquitto y envía datos desde tu ESP32
Qué es MQTT y por qué lo usa todo el IoT, cómo instalar el broker Mosquitto en Windows o Linux, y cómo publicar datos y recibir órdenes desde un ESP32.
Lire en français →Algunos enlaces de este artículo son de afiliado: si compras a través de ellos, BeInTech recibe una pequeña comisión sin coste extra para ti. Así se mantiene el blog.
Si te metes en IoT o en domótica, vas a oír hablar de MQTT constantemente: lo usan Home Assistant, Zigbee2MQTT, Tasmota, ESPHome y casi cualquier sensor conectado. En esta guía entenderás cómo funciona en 5 minutos, montarás tu propio servidor con Mosquitto y harás que un ESP32 envíe datos y reciba órdenes.
Qué es MQTT (sin tecnicismos)
MQTT es un protocolo de mensajería muy ligero, pensado para dispositivos pequeños y redes poco fiables. Funciona como un tablón de anuncios:
- El broker es el tablón: un servidor que recibe todos los mensajes y los reparte. El más usado es Mosquitto.
- Los dispositivos publican mensajes en un tema (topic), por ejemplo
casa/salon/temperatura. - Quien esté suscrito a ese tema recibe el mensaje al instante.
Lo importante: el que publica y el que recibe no se conocen. El sensor del salón no sabe si sus datos los lee Home Assistant, una app del móvil o un script de Python. Solo habla con el broker. Por eso es tan fácil añadir dispositivos.
Los temas (topics)
Los temas son rutas separadas por /, que organizas como quieras:
casa/salon/temperatura
casa/salon/humedad
casa/cocina/luz/set
casa/cocina/luz/estado
Al suscribirte puedes usar comodines:
+sustituye un nivel:casa/+/temperaturarecibe la temperatura de todas las habitaciones.#sustituye todo lo que sigue:casa/#recibe absolutamente todo lo de la casa.
Tres conceptos que te encontrarás
- QoS (calidad de servicio):
0= se envía una vez y no se comprueba;1= se garantiza que llega al menos una vez;2= exactamente una vez. Para sensores, QoS 0 o 1 es suficiente. - Retain (mensaje retenido): el broker guarda el último mensaje del tema y se lo entrega a quien se suscriba más tarde. Útil para estados (la luz está encendida).
- Last Will (último deseo): un mensaje que el broker publica automáticamente si el dispositivo se desconecta de golpe, por ejemplo
offline. Así sabes si un sensor se ha caído.
Paso 1: instala Mosquitto
En Linux o Raspberry Pi
sudo apt update
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable --now mosquitto
En Windows
Descarga el instalador desde la web oficial (mosquitto.org, sección Download) e instálalo con las opciones por defecto. Se instala en C:\Program Files\mosquitto y como servicio de Windows.
Permite conexiones desde la red
Desde la versión 2, Mosquitto solo acepta conexiones desde el propio ordenador por seguridad. Para que el ESP32 pueda conectarse, edita el archivo de configuración (/etc/mosquitto/conf.d/beintech.conf en Linux, o mosquitto.conf en la carpeta de instalación en Windows) y añade:
listener 1883
allow_anonymous true
Reinicia el servicio (sudo systemctl restart mosquitto en Linux, o desde Servicios en Windows). En Windows, acepta el aviso del firewall o abre el puerto 1883 para la red privada.
Esta configuración es solo para probar en tu red local. Más abajo te explico cómo ponerle usuario y contraseña. Nunca abras el puerto 1883 a Internet en tu router.
Paso 2: prueba que funciona
Abre dos terminales. En la primera, suscríbete a todo lo de la casa:
mosquitto_sub -h localhost -t "casa/#" -v
En la segunda, publica un mensaje:
mosquitto_pub -h localhost -t "casa/salon/temperatura" -m "21.5"
En la primera terminal aparecerá casa/salon/temperatura 21.5. Ya tienes tu broker funcionando. Deja la primera terminal abierta: la usarás para ver lo que manda el ESP32.
Apunta también la IP del ordenador donde está Mosquitto (en Windows, comando ipconfig; en Linux, hostname -I). La necesitas para el ESP32.
Paso 3: el ESP32 publica datos
Usaremos el montaje de la estación meteorológica con BME280. Instala en Arduino IDE la librería PubSubClient (de Nick O’Leary) desde el Gestor de librerías.
Este programa publica la temperatura, humedad y presión cada 30 segundos, y además escucha órdenes para encender o apagar el LED de la placa:
#include <WiFi.h>
#include <PubSubClient.h>
#include <Wire.h>
#include <Adafruit_BME280.h>
const char* WIFI_SSID = "NOMBRE_DE_TU_WIFI";
const char* WIFI_PASS = "TU_CONTRASEÑA";
const char* MQTT_SERVER = "192.168.1.10"; // IP del ordenador con Mosquitto
const int MQTT_PORT = 1883;
const char* CLIENT_ID = "esp32-salon";
const int LED_PIN = 2;
const uint8_t BME_ADDR = 0x76;
WiFiClient wifiClient;
PubSubClient mqtt(wifiClient);
Adafruit_BME280 bme;
unsigned long ultimoEnvio = 0;
// Se ejecuta cada vez que llega un mensaje a un tema suscrito
void alRecibirMensaje(char* topic, byte* payload, unsigned int length) {
String mensaje;
for (unsigned int i = 0; i < length; i++) mensaje += (char)payload[i];
Serial.printf("Recibido [%s]: %s\n", topic, mensaje.c_str());
if (String(topic) == "casa/salon/led/set") {
bool encender = (mensaje == "ON");
digitalWrite(LED_PIN, encender ? HIGH : LOW);
mqtt.publish("casa/salon/led/estado", encender ? "ON" : "OFF", true);
}
}
void conectarMQTT() {
while (!mqtt.connected()) {
Serial.print("Conectando a MQTT... ");
// Último deseo: si nos desconectamos de golpe, el broker publica "offline"
if (mqtt.connect(CLIENT_ID, "casa/salon/estado", 1, true, "offline")) {
Serial.println("OK");
mqtt.publish("casa/salon/estado", "online", true);
mqtt.subscribe("casa/salon/led/set");
} else {
Serial.printf("fallo (rc=%d). Reintento en 5 s\n", mqtt.state());
delay(5000);
}
}
}
void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
if (!bme.begin(BME_ADDR)) {
Serial.println("No se encuentra el BME280");
while (true) delay(1000);
}
WiFi.mode(WIFI_STA);
WiFi.begin(WIFI_SSID, WIFI_PASS);
while (WiFi.status() != WL_CONNECTED) delay(500);
Serial.print("Wi-Fi OK, IP: ");
Serial.println(WiFi.localIP());
mqtt.setServer(MQTT_SERVER, MQTT_PORT);
mqtt.setCallback(alRecibirMensaje);
}
void loop() {
if (!mqtt.connected()) conectarMQTT();
mqtt.loop(); // imprescindible: procesa mensajes entrantes y mantiene la conexión
if (millis() - ultimoEnvio > 30000 || ultimoEnvio == 0) {
ultimoEnvio = millis();
char valor[16];
snprintf(valor, sizeof(valor), "%.1f", bme.readTemperature());
mqtt.publish("casa/salon/temperatura", valor);
snprintf(valor, sizeof(valor), "%.1f", bme.readHumidity());
mqtt.publish("casa/salon/humedad", valor);
snprintf(valor, sizeof(valor), "%.1f", bme.readPressure() / 100.0F);
mqtt.publish("casa/salon/presion", valor);
Serial.println("Datos publicados");
}
}
Cambia la IP en MQTT_SERVER, sube el programa y mira la terminal donde tenías mosquitto_sub. Verás llegar los datos:
casa/salon/estado online
casa/salon/temperatura 22.3
casa/salon/humedad 48.1
casa/salon/presion 1012.7
Paso 4: controla el ESP32 desde el ordenador
Ahora al revés. Desde una terminal, envía:
mosquitto_pub -h localhost -t "casa/salon/led/set" -m "ON"
El LED de la placa se enciende, y el ESP32 confirma con casa/salon/led/estado ON. Envía OFF para apagarlo. Si cambias el LED por un relé, ya estás controlando un enchufe desde la red.
Fíjate en el patrón: un tema /set para dar órdenes y otro /estado para informar del estado real. Es la convención que usa casi todo el mundo, y la que espera Home Assistant.
Paso 5: protege tu broker con contraseña
Cuando todo funcione, desactiva el acceso anónimo. En Linux:
sudo mosquitto_passwd -c /etc/mosquitto/passwd esp32
Te pedirá una contraseña. Después cambia la configuración por:
listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
Reinicia Mosquitto y, en el código del ESP32, conéctate con usuario y contraseña:
mqtt.connect(CLIENT_ID, "esp32", "TU_CONTRASEÑA_MQTT",
"casa/salon/estado", 1, true, "offline");
Las herramientas de terminal también la necesitarán: añade -u esp32 -P TU_CONTRASEÑA_MQTT a mosquitto_sub y mosquitto_pub.
Errores típicos
| Error | Causa probable |
|---|---|
rc=-2 en el ESP32 |
No llega al broker: IP equivocada, Mosquitto solo escucha en localhost o el firewall bloquea el puerto 1883 |
rc=5 |
Usuario o contraseña incorrectos (o falta allow_anonymous true) |
| Se conecta y desconecta todo el rato | Dos dispositivos con el mismo CLIENT_ID: cada uno debe tener uno distinto |
| No llegan los mensajes entrantes | Falta llamar a mqtt.loop() en el loop() |
Siguientes pasos
Ya tienes un sistema IoT de verdad: sensores que publican datos y actuadores que obedecen órdenes, todo a través de un broker propio. El siguiente paso natural es conectar esto a Home Assistant para tener gráficas, un panel en el móvil y automatizaciones del tipo si la humedad pasa del 70 %, enciende el deshumidificador.
Si quieres un servidor dedicado para Mosquitto y Home Assistant que esté siempre encendido y consuma poco, una Raspberry Pi es la opción más popular:
Raspberry Pi 5 (4 GB)
Suficiente para Mosquitto, Home Assistant y Zigbee2MQTT a la vez. Añade una fuente oficial y una buena tarjeta o SSD.