Ejemplos de mosquitto_pub y mosquitto_sub: 25 comandos prácticos para probar MQTT

Estos ejemplos de mosquitto_pub y mosquitto_sub son los comandos que de verdad usarás para probar dispositivos, depurar topics y automatizar MQTT con scripts. Todos están listos para copiar y pegar y se ejecutan contra el servidor MQTT público gratuito broker.connectmq.com, pensado para pruebas, así que puedes comprobar su comportamiento tú mismo en segundos. Al terminar sabrás cómo poner a prueba QoS, mensajes retenidos, Last Will, TLS y propiedades de MQTT 5 desde la línea de comandos.

Antes de empezar

Instala los clientes de Mosquitto:

# Debian / Ubuntu / Raspberry Pi OS
sudo apt install mosquitto-clients

# macOS
brew install mosquitto

# Windows: instala Mosquitto desde mosquitto.org; el instalador incluye mosquitto_pub.exe y mosquitto_sub.exe

Compruébalo con mosquitto_pub --help; la primera línea muestra la versión. Varios de los ejemplos siguientes necesitan la versión 2.x (para -x, la salida %j y algunas opciones de MQTT 5). La referencia completa de opciones está en el manual oficial de mosquitto_pub.

Tres reglas para el servidor público:

• Pasa siempre un client ID único y no vacío con -i. Dos clientes con el mismo ID se desconectan mutuamente.
• Usa un prefijo de topic único. Los ejemplos usan connectmq/demo/x7q2/; sustituye x7q2 por tu propia cadena aleatoria.
• El área pública la puede leer cualquiera. Nunca publiques credenciales ni datos personales.

Para acortar los comandos, define dos variables de shell (bash/zsh):

H="-h broker.connectmq.com -p 1883"
T="connectmq/demo/x7q2"

Abre dos terminales: una para mosquitto_sub y otra para mosquitto_pub.

Ejemplos básicos de mosquitto_pub y mosquitto_sub

1. Suscribirse a un topic

mosquitto_sub $H -i sub-x7q2 -t "$T/hello"

2. Publicar un mensaje

mosquitto_pub $H -i pub-x7q2 -t "$T/hello" -m "hello from the CLI"

3. Suscribirse a todo lo que cuelga de tu prefijo e imprimir los topics (-v imprime el topic antes del payload)

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v

4. Comodín de un solo nivel: todos los topics de temperatura, de cualquier habitación

mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -v

5. Varios filtros de topic en un mismo cliente

mosquitto_sub $H -i sub-x7q2 -t "$T/+/temperature" -t "$T/+/humidity" -v

6. Publicar JSON (las comillas simples impiden que la shell interprete las llaves y las comillas)

mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 21.8, "unit": "C"}'

En cmd.exe de Windows, escapa en su lugar las comillas internas: -m "{\"value\": 21.8}".

QoS y sesiones

7. Publicar y suscribirse con QoS 1

mosquitto_sub $H -i sub-x7q2 -t "$T/alarms" -q 1 -v
mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 1 -m "door open"

El QoS efectivo es el menor entre el QoS de publicación y el de la suscripción. Para el panorama completo, consulta los niveles de QoS de MQTT explicados.

8. Observar el intercambio del protocolo con -d (el modo debug muestra CONNECT, PUBLISH, PUBACK y compañía)

mosquitto_pub $H -i pub-x7q2 -t "$T/alarms" -q 2 -m "test" -d

Verás PUBLISH, PUBREC, PUBREL y PUBCOMP para QoS 2. Es la forma más rápida de demostrar lo que hace realmente un broker.

9. Sesión persistente: recibir los mensajes publicados mientras estabas desconectado

# Suscríbete una vez con un ID fijo y la clean session desactivada; después Ctrl+C
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v
# Mientras está detenido, publica con QoS 1
mosquitto_pub $H -i pub-x7q2 -q 1 -t "$T/queue" -m "queued while offline"
# Reconéctate con el mismo ID y -c: el mensaje se entrega
mosquitto_sub $H -i sub-persist-x7q2 -c -q 1 -t "$T/queue" -v

10. Expiración de sesión de MQTT 5 (conserva la sesión 300 segundos tras la desconexión)

mosquitto_sub $H -V 5 -i sub-persist-x7q2 -c -x 300 -q 1 -t "$T/queue" -v

El broker público conserva las sesiones como máximo 30 minutos.

Mensajes retenidos

11. Publicar un estado retenido

mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -m "running"

Cualquier suscriptor nuevo recibe running de inmediato, sin esperar a la siguiente publicación.

12. Mostrar solo los mensajes retenidos y salir

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v --retained-only -W 3

-W 3 sale a los 3 segundos, algo muy útil en scripts que toman una instantánea del estado actual.

13. Ignorar los mensajes retenidos antiguos (-R omite los mensajes que llegan con el flag de retención activado)

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -v -R

14. Borrar un mensaje retenido (publica un payload retenido vacío)

mosquitto_pub $H -i pub-x7q2 -t "$T/pump1/state" -r -n

15. Limpiar todos los mensajes retenidos bajo tu prefijo

mosquitto_sub $H -i cleaner-x7q2 -t "$T/#" --remove-retained --retained-only -W 3

Úsalo con cuidado en cualquier broker; elimina el estado retenido de todo lo que coincida con el filtro.

Last Will and Testament

16. Registrar un Last Will que marque el cliente como desconectado

mosquitto_sub $H -i device-x7q2 -t "$T/device1/cmd" \
  --will-topic "$T/device1/status" --will-payload "offline" --will-retain --will-qos 1

En otra terminal, observa el estado con mosquitto_sub $H -i watch-x7q2 -t "$T/device1/status" -v y luego mata el primer proceso de golpe (cerrando la terminal o con kill -9). Cuando vence el keep-alive, el broker publica offline. Un Ctrl+C limpio envía DISCONNECT y no activa el Will. Define un keep-alive corto con -k 10 para verlo antes.

Scripts y control de la salida

17. Recibir exactamente N mensajes y salir

mosquitto_sub $H -i sub-x7q2 -t "$T/kitchen/temperature" -C 1

Ideal en scripts de shell: TEMP=$(mosquitto_sub ... -C 1).

18. Formato de salida personalizado con marcas de tiempo

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "@Y-@m-@dT@H:@M:@S %t %p"

19. Salida JSON para encadenarla con jq

mosquitto_sub $H -i sub-x7q2 -t "$T/#" -F "%j" | jq -c '{topic, payload}'

20. Publicar cada línea de un archivo o de stdin como un mensaje independiente

printf '20.1\n20.4\n20.9\n' | mosquitto_pub $H -i pub-x7q2 -t "$T/kitchen/temperature" -l

Usa -f firmware.bin para enviar un archivo completo como un único mensaje, o -s para enviar todo stdin como un solo mensaje. El broker público limita los mensajes a 64 KB.

21. Un pequeño simulador de sensor (respeta el límite público de 10 mensajes por segundo por cliente)

while true; do
  mosquitto_pub $H -i sim-x7q2 -t "$T/lab/temperature" \
    -m "{\"value\": $((RANDOM % 10 + 20)), \"ts\": $(date +%s)}"
  sleep 1
done

TLS y autenticación

22. Conexión cifrada en el puerto 8883

# Linux: usa el paquete de CA del sistema
mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i tls-x7q2 -t "$T/#" -v

En macOS o Windows, apunta --cafile a un archivo PEM que contenga el certificado ISRG Root X1 (Let's Encrypt), ya que esos sistemas no exponen un directorio PEM. Si ves Error: A TLS error occurred, revisa la ruta del archivo de CA y el reloj del sistema.

23. Broker privado con credenciales

mosquitto_pub -h YOUR_BROKER_HOST -p 8883 --capath /etc/ssl/certs \
  -i YOUR_CLIENT_ID -u YOUR_USERNAME -P YOUR_PASSWORD \
  -t "factory1/line1/cnc1/telemetry" -q 1 -m '{"spindle_rpm": 8000}'

En entornos compartidos, evita que las contraseñas queden en el historial de la shell. Mosquitto 2.x lee opciones desde un archivo de configuración: pon las líneas -u y -P en ~/.config/mosquitto_pub (y mosquitto_sub) con permisos restrictivos.

Propiedades de MQTT 5

24. Content type, propiedad de usuario y expiración del mensaje

mosquitto_pub $H -V 5 -i pub-x7q2 -t "$T/kitchen/temperature" -m '{"value": 22}' \
  -D PUBLISH content-type application/json \
  -D PUBLISH user-property source cli-test \
  -D PUBLISH message-expiry-interval 60

Visualiza las propiedades en el lado del suscriptor con -V 5 -F "%t %p | %P" (%P imprime las propiedades de usuario). La guía de funciones de MQTT 5 explica cuándo es útil cada propiedad.

25. Solicitud/respuesta con mosquitto_rr

# Respondedor: lee el response topic (%R) de cada solicitud y la contesta
while true; do
  RT=$(mosquitto_sub $H -V 5 -i resp-x7q2 -t "$T/rpc/time" -C 1 -F "%R")
  mosquitto_pub $H -V 5 -i resp-pub-x7q2 -t "$RT" -m "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
done &

# Solicitante: fija el response topic, espera una respuesta y la imprime
mosquitto_rr $H -V 5 -i req-x7q2 -t "$T/rpc/time" -e "$T/rpc/time/reply" -m "now?" -W 5

mosquitto_rr fija el response topic de MQTT 5 en la solicitud, se suscribe a él e imprime la primera respuesta. El respondedor en shell basta para una demo; un servicio real en Python o Node también devolvería los correlation data para poder emparejar solicitudes concurrentes.

Referencia rápida de opciones

Solución de problemas

• Connection Refused: identifier rejected: client ID vacío o no válido. Pasa -i con un valor único.
• La conexión se cae justo después de conectar: otro proceso usa el mismo client ID.
• Error: Connection refused en el puerto 8883: olvidaste --capath o --cafile, así que el cliente intentó TCP sin cifrar en un puerto TLS.
• No llega nada: compara carácter a carácter el filtro de suscripción y el topic de publicación; los topics MQTT distinguen mayúsculas y minúsculas, y una / inicial crea un nivel vacío adicional.
• Los mensajes se detienen tras una ráfaga: límites del broker público (10 mensajes por segundo por cliente, 10 suscripciones por cliente, 8 niveles de topic).

De las pruebas a producción

El servidor público es perfecto para aprender estos comandos, pero los dispositivos sobre el terreno necesitan credenciales privadas y aislamiento. Un broker MQTT gestionado de ConnectMQ te da TLS en el 8883, WebSocket en el 8083 y el 8084, MQTT 3.1.1 y 5.0, y credenciales generadas por broker; todos los comandos anteriores funcionan sustituyendo los flags del ejemplo 23. Para otras opciones de línea de comandos, lee la comparativa de herramientas CLI de MQTT, y si prefieres una interfaz gráfica, consulta las aplicaciones de escritorio tipo MQTT Explorer. La guía de bibliotecas cliente MQTT muestra cómo trasladar estas pruebas al código.

Empieza con ConnectMQ

Crea un broker privado en app.connectmq.com con el plan Serverless gratuito, sin tarjeta de crédito. Copia el usuario, la contraseña y el client ID generados en los ejemplos 22 y 23, y usa el explorador de topics en vivo del portal junto a mosquitto_sub para confirmar cada mensaje.

Preguntas frecuentes

¿Por qué mosquitto_sub no muestra nada cuando publico?

Lo más habitual es que el filtro de topic no coincida: revisa mayúsculas, barras y comodines. Asegúrate también de que los dos clientes usan client ID distintos y añade -d para ver si se concedió la suscripción.

¿Cómo envío un mensaje sin payload con mosquitto_pub?

Usa -n. Combinado con -r, borra el mensaje retenido de ese topic.

¿Puede mosquitto_pub usar MQTT 5?

Sí, desde Mosquitto 1.6. Añade -V 5 (o -V mqttv5) y define las propiedades con -D <command> <property> <value>.

¿Necesito tener instalado el broker Mosquitto para usar estos comandos?

No. El paquete mosquitto-clients contiene solo los clientes de línea de comandos, y funcionan con cualquier broker MQTT, incluido ConnectMQ.