Las convenciones de nombres de topics MQTT deciden si tu sistema sigue siendo fácil de suscribir, seguro y depurable a medida que pasa de cinco dispositivos a cinco mil. Esta guía te ofrece 12 reglas concretas con ejemplos buenos y malos, una plantilla reutilizable y una lista de comprobación que puedes aplicar antes de que salga el primer dispositivo.
Por qué los nombres de topic merecen una convención
Los topics MQTT son cadenas UTF-8 de formato libre separadas por /. El broker no impone ninguna estructura, y los topics se crean sobre la marcha cuando alguien publica. Esa libertad resulta cómoda el primer día y dolorosa el día 300, cuando los suscriptores dependen de docenas de grafías ligeramente distintas, los comodines coinciden con datos equivocados y nadie se atreve a renombrar nada porque podrían romperse consumidores desconocidos.
Los nombres de topic son, en la práctica, la API pública de tu sistema. Cada suscriptor, dashboard, flujo de Node-RED y regla de acceso depende de ellos. Acordar una convención pronto es una de las mejoras de fiabilidad más baratas que existen.
Las 12 convenciones de nombres de topics MQTT
1. No empieces con una barra
Una / inicial crea un primer nivel vacío. /factory/line1 y factory/line1 son topics distintos, y el nivel vacío no aporta más que confusión.
- Mal:
/factory/line1/temp - Bien:
factory/line1/temp
2. Usa solo minúsculas
Los topics distinguen entre mayúsculas y minúsculas. Line1/Temp y line1/temp son topics distintos, y mezclar mayúsculas garantiza que alguien se suscriba al equivocado. Elige minúsculas y mantente fiel a ellas.
3. Evita espacios y caracteres especiales
Los espacios, las tildes y los símbolos son legales, pero causan problemas de escapado en shells, URLs, logs y archivos de configuración. Usa a-z, 0-9, - y _. No uses nunca + ni # dentro de los nombres; son caracteres comodín en las suscripciones.
- Mal:
Plant A/Pump #3/Pressure (bar) - Bien:
plant-a/pump-3/pressure
4. Ve de lo general a lo específico
Ordena los niveles del ámbito más amplio al más estrecho, para que los comodines puedan seleccionar ramas completas. Una forma habitual es:
<namespace>/<site>/<area>/<line-or-group>/<device>/<category>/<measurement>
Con este orden, acme/berlin/# selecciona una planta y acme/+/+/+/+/telemetry/temperature selecciona todas las lecturas de temperatura. El orden inverso hace imposibles estas suscripciones. Consulta los comodines de MQTT para ver cómo coinciden + y #.
5. Empieza con un namespace
Un primer nivel como el nombre de tu empresa, producto o aplicación mantiene tu tráfico separado del de otros sistemas que comparten el mismo broker, y facilita los bridges o las migraciones más adelante. En el servidor MQTT público gratuito, pensado para pruebas y no para datos de producción, un prefijo único como connectmq/demo/<random-id>/ mantiene tus experimentos alejados de los de los demás.
6. Pon los IDs de dispositivo después de la ubicación, no antes
Los identificadores pertenecen al nivel que representa el dispositivo, después de los niveles de agrupación que describen dónde está. Así puedes suscribirte a una ubicación sin conocer todos los IDs de dispositivo, y a un solo dispositivo con un único topic exacto.
- Mal:
esp32-a4cf12/berlin/hall2/temperature - Bien:
acme/berlin/hall2/esp32-a4cf12/telemetry/temperature
7. Separa las categorías de mensajes
Mantén la telemetría, el estado, los comandos y los eventos en ramas distintas. Así, los suscriptores y las reglas de acceso pueden apuntar exactamente a lo que necesitan.
| Categoría | Topic de ejemplo | QoS / retain típicos |
|---|---|---|
| Telemetría | acme/berlin/hall2/pump-3/telemetry/pressure |
QoS 0, no retenido |
| Estado | acme/berlin/hall2/pump-3/state/running |
QoS 1, retenido |
| Status | acme/berlin/hall2/pump-3/status |
QoS 1, retenido, fijado por el Last Will |
| Comandos | acme/berlin/hall2/pump-3/cmd/set-speed |
QoS 1, no retenido |
| Eventos / alarmas | acme/berlin/hall2/pump-3/event/overpressure |
QoS 1, no retenido |
8. Versiona tu contrato de payload
Cuando cambian los formatos de payload, los consumidores se rompen. Pon una versión en un lugar fácil de enrutar, ya sea como nivel de topic (acme/v2/...) o como campo dentro de cada payload. Una versión en el topic permite que consumidores antiguos y nuevos convivan durante la migración.
9. Mantén una profundidad razonable
Cada nivel debe tener significado. Siete u ocho niveles son más que suficientes para la mayoría de los sistemas, y algunos brokers imponen un límite; el servidor MQTT público gratuito de ConnectMQ permite hasta 8 niveles. Los árboles profundos también cuestan ancho de banda, porque la cadena completa del topic se envía con cada mensaje (los alias de topic de MQTT 5 ayudan, pero no arreglan un mal diseño).
10. No pongas datos ni secretos en el topic
Los valores, las marcas de tiempo, los tokens y los datos personales van en el payload. Un topic como acme/pump-3/pressure/4.2 crea un topic nuevo por cada lectura y rompe los mensajes retenidos y las suscripciones. Los nombres de topic también aparecen en logs y herramientas de monitorización, así que nunca incluyas credenciales ni información personal.
11. Usa sustantivos en singular y estables
Elige una palabra por concepto y documéntala: temperature, no temp en un sitio y Temperature_C en otro. Las unidades van en el payload o en la documentación, no en el nombre del topic, salvo que la misma medida se publique realmente en varias unidades.
12. Reserva $ para el broker
Los topics que empiezan por $ están reservados para uso interno del broker, como las estadísticas $SYS/..., y una suscripción simple a # no los incluye. No crees tus propios topics con $. Descubre qué publica tu broker ahí en los topics $SYS de MQTT.
Árboles de topics buenos y malos, uno al lado del otro
# Difícil de usar
/Factory1/Line 1/CNC#1/Temp
cnc1/factory1/temperature/71.3
Factory1/line1/CNC1/TEMP_C
# Fácil de usar
acme/factory1/machining/line1/cnc1/telemetry/spindle-temperature
acme/factory1/machining/line1/cnc1/state/mode
acme/factory1/machining/line1/cnc1/status
acme/factory1/machining/line1/cnc1/cmd/start
El segundo árbol sigue la jerarquía de estilo ISA-95 (empresa, planta, área, línea y celda) que se usa a menudo en un Unified Namespace. Si trabajas en entornos industriales, la guía de Sparkplug B y Unified Namespace explica cómo se estandarizan estas jerarquías. Para ver más árboles listos para usar, consulta nuestros ejemplos de jerarquías de topics MQTT.
Prueba tu convención en un broker real
Publica unos cuantos mensajes con la estructura que propones en broker.connectmq.com y comprueba que las suscripciones con comodines seleccionan exactamente lo que esperas. Sustituye n8x4 por tu propia cadena aleatoria; cualquiera puede leer el área pública. La demostración omite el nivel de área para que el topic completo no supere el límite de 8 niveles del broker público.
P="connectmq/demo/n8x4/factory1/line1"
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc1/telemetry/spindle-temperature" -m '{"v":71.3,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc2/telemetry/spindle-temperature" -m '{"v":68.9,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-r -q 1 -t "$P/cnc1/status" -m 'online'
# Toda la telemetría de line1, nada más
mosquitto_sub -h broker.connectmq.com -p 1883 -i naming-sub-n8x4 -v \
-t "connectmq/demo/n8x4/factory1/line1/+/telemetry/#"
Solo el mensaje retenido status se habría entregado de inmediato a un suscriptor nuevo; la telemetría anterior se publicó antes de que se conectara el suscriptor y no estaba retenida. Vuelve a publicar con el suscriptor en marcha para verla llegar.
Lista de comprobación de la convención de topics
- Un documento escrito recoge cada nivel, su significado y sus valores permitidos.
- Todos los topics están en minúsculas, sin barra inicial, espacios ni caracteres comodín.
- El primer nivel es un namespace.
- Los niveles van de lo general a lo específico, con el ID de dispositivo después de su ubicación.
- La telemetría, el estado, el status, los comandos y los eventos tienen ramas separadas.
- Existe una estrategia de versionado.
- No aparecen valores, marcas de tiempo ni secretos en los topics.
- La profundidad se mantiene dentro de los límites del broker.
- Se han probado las suscripciones con comodines de todos los consumidores conocidos.
- El árbol se ha revisado en un explorador de topics con datos realistas.
Si estás empezando desde cero, el tutorial de MQTT trata conjuntamente topics, suscripciones y QoS.
Visualiza tu árbol de topics en ConnectMQ
ConnectMQ ofrece a cada broker un explorador de topics en directo, para que veas crecer tu jerarquía en tiempo real y detectes al instante las grafías extraviadas. También reconoce los topics de estilo ISA-95 y Unified Namespace y muestra los dispositivos por nivel ISA-95, lo que recompensa una convención disciplinada. Como broker MQTT gestionado, admite MQTT 3.1.1 y 5.0 sobre TCP, TLS y WebSockets. Crea un broker Serverless gratuito, sin tarjeta de crédito, y prueba tu convención de topics con dispositivos reales.
Preguntas frecuentes
¿Deben empezar con una barra los topics MQTT?
No. Una barra inicial crea un primer nivel de topic vacío, lo que hace los topics más difíciles de leer y fáciles de escribir mal. Empieza directamente con tu namespace, como acme/....
¿Distinguen los topics MQTT entre mayúsculas y minúsculas?
Sí. Sensor/Temp y sensor/temp son topics completamente distintos. Usar minúsculas en todas partes evita discrepancias accidentales.
¿Cuántos niveles debe tener un topic MQTT?
Tantos como aporten significado y ni uno más; la mayoría de los sistemas necesitan entre cuatro y ocho. Comprueba también los límites del broker: el servidor MQTT público gratuito de ConnectMQ permite hasta 8 niveles.
¿Dónde debe ir el ID de dispositivo en un topic MQTT?
Después de los niveles que describen la ubicación o la agrupación, y antes de la categoría del mensaje y la medida. Ese orden permite que los comodines seleccionen limpiamente una planta, una línea o un único dispositivo.
