Tutorial de MQTTX: prueba brokers con el cliente de escritorio y la CLI

MQTTX es un cliente MQTT de código abierto de EMQ que existe en tres variantes: una app de escritorio (Windows, macOS, Linux), una herramienta de línea de comandos llamada mqttx y una versión para navegador. Habla MQTT 3.1, 3.1.1 y 5.0 sobre TCP, TLS, WebSocket y WebSocket seguro, y funciona con cualquier broker compatible, no solo con EMQX.

Este tutorial recorre las partes que los desarrolladores usan de verdad al probar un broker: configurar conexiones, inspeccionar propiedades de MQTT 5, transformar payloads con scripts y manejar la CLI para pub/sub con scripts, dispositivos simulados y pruebas de carga con mqttx bench.

Instalar MQTTX

Comprueba la CLI con mqttx --version. Si solo necesitas una comprobación rápida desde el navegador sin instalar nada, el cliente MQTT online de este sitio hace lo mismo en lo básico de pub/sub sobre WebSocket.

La app de escritorio: conexiones iguales a producción

Haz clic en New Connection y rellena los campos exactamente como los usarán tus dispositivos: una prueba que difiere de producción no demuestra nada.

En Advanced encontrarás keep-alive, timeout de conexión, reconexión automática y, para MQTT 5, las propiedades de CONNECT: session expiry interval, receive maximum, maximum packet size, topic alias maximum y user properties. La sección Last Will configura el topic, payload, QoS, flag retain y will delay interval del testamento: útil para probar la entrega del Last Will.

Si una conexión falla, el error aparece en el log de la conexión. Los brokers MQTT 5 devuelven un reason code; pégalo en el buscador de reason codes para ver qué significa.

Suscribirse y publicar

Usa New Subscription con un filtro de topic como testmqtt/mqttx/#. Cada suscripción recibe un color, y los mensajes entrantes se tiñen con el color de la suscripción que coincidió: la forma más rápida de ver wildcards que se solapan. ¿No estás seguro de que un filtro coincide? Pruébalo en el topic matcher.

En la parte inferior de la ventana está el cuadro de publicación: topic, QoS, flag retain y payload. El selector de tipo de payload (Plaintext, JSON, Base64, Hex y otros según la versión) controla tanto cómo escribes el mensaje saliente como cómo se decodifican los payloads entrantes. El modo JSON valida y formatea, lo que detecta telemetría rota al instante.

Para MQTT 5, haz clic en el icono de propiedades junto al cuadro de publicación para definir:

• Content type y payload format indicator
• Message expiry interval
• Topic alias
• Response topic y correlation data para request/response
• User properties como pares clave/valor

Los mensajes recibidos muestran sus propiedades en la burbuja del mensaje, así puedes confirmar que el broker las reenvió. Eso convierte a MQTTX en un buen complemento manual para las pruebas de funciones de MQTT 5.

Scripts y mensajes programados

La función Script te permite escribir una pequeña función JavaScript que transforma un payload antes de publicarlo o después de recibirlo. El ejemplo clásico simula un sensor:

/**
 * Sustituye temperatura y humedad por valores aleatorios en cada publicación.
 * @param value el payload escrito en el cuadro de publicación, p. ej. {}
 */
function handlePayload(value) {
  let data = value;
  if (typeof value === 'string') {
    data = JSON.parse(value);
  }
  data.temperature = Math.round(Math.random() * 400) / 10;
  data.humidity = Math.floor(Math.random() * 100);
  return JSON.stringify(data, null, 2);
}

execute(handlePayload);

Guarda el script, aplícalo a la conexión (mensajes publicados, recibidos o ambos) y combínalo con Timed Message para publicar cada pocos segundos. Ya tienes un dispositivo falso sin escribir un cliente completo. La API de scripts ha cambiado entre versiones, así que revisa los ejemplos integrados de tu versión si execute no se reconoce.

La CLI mqttx

La CLI es donde MQTTX brilla para pruebas repetibles. Cuatro subcomandos cubren casi todo: conn, sub, pub y bench.

mqttx conn -h broker.connectmq.com -p 1883 \
  -u "$MQTT_USER" -P "$MQTT_PASS" -i testmqtt-cli-check

mqttx sub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/#' -q 1 -v

mqttx pub -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sensor-1' -q 1 -r \
  -m '{"temperature":21.5}'

-v imprime el topic junto a cada payload, algo imprescindible con wildcards. Otras opciones que usarás:

Esta es la misma publicación sobre WebSocket seguro, que es lo que usaría una app de navegador:

mqttx pub -h broker.connectmq.com -p 8084 -l wss --path /mqtt \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/mqttx/ws' -m 'hello over wss'

Ejecuta mqttx pub --help para ver la lista completa; de vez en cuando se añaden o renombran flags entre versiones.

Dispositivos simulados

mqttx simulate publica datos realistas a partir de escenarios integrados o de tu propio archivo de script. Lista los escenarios disponibles en tu versión con mqttx ls --scenarios y ejecuta uno:

mqttx simulate -sc tesla -c 10 \
  -h broker.connectmq.com -p 1883 \
  -t 'testmqtt/mqttx/sim/%c'

%c se expande al client ID, así cada dispositivo simulado tiene su propio topic. Suscríbete a testmqtt/mqttx/sim/# en otra terminal para ver el flujo.

Pruebas de carga con mqttx bench

mqttx bench ejecuta benchmarks de conexión, publicación y suscripción desde un solo proceso:

mqttx bench conn -c 500 -i 10 \
  -h broker.connectmq.com -p 1883 -u "$MQTT_USER" -P "$MQTT_PASS"

mqttx bench sub -c 50 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883

mqttx bench pub -c 50 -im 100 -t 'testmqtt/bench/%i' -q 1 \
  -h broker.connectmq.com -p 1883 -m '{"v":1}'

%i es el índice del cliente, así que el publisher 7 habla con el suscriptor 7. La salida muestra los clientes conectados y la tasa de mensajes por segundo; cuando la tasa recibida en la terminal 1 se queda por debajo de la enviada en la terminal 2, algo entre los clientes y el broker está saturado. Para interpretar esos números, y para herramientas más potentes, consulta pruebas de carga de brokers MQTT.

¿Escritorio o CLI?

• Escritorio cuando exploras: comparar formatos de payload, observar varias suscripciones, probar a mano propiedades de MQTT 5.
• CLI cuando repites: scripts de shell, pipelines de CI, servidores a los que accedes por SSH y todo lo que quieras pegar en un informe de bug.
• Ninguno cuando necesitas aserciones. MQTTX muestra mensajes; no hace fallar una build. Para comprobaciones automáticas, envuelve mqttx en un script que valide la salida, o escribe tests con una librería cliente: consulta pruebas MQTT en GitHub Actions.

Si quieres comparar MQTTX con MQTT Explorer, la CLI de HiveMQ y otras herramientas, consulta la comparativa de clientes MQTT de escritorio.

Mira tus mensajes de MQTTX en el navegador

MQTTX cubre todo el ciclo, desde hacer clic por la interfaz hasta benchmarks con scripts, con una sola herramienta y un solo conjunto de ajustes de conexión. Guarda una conexión por entorno, mantén tus comandos de la CLI en el repositorio junto a tu firmware y podrás reproducir cualquier problema del broker en un minuto.

Preguntas frecuentes