Estos ejemplos de jerarquía de topics MQTT te ofrecen árboles ya preparados para cuatro tipos de proyecto habituales: un hogar inteligente, una flota de vehículos, una fábrica y un sistema de monitorización energética. Para cada uno verás el árbol, las suscripciones a las que está pensado para dar servicio y las decisiones que hay detrás, para que puedas adaptarlo en lugar de empezar desde una página en blanco.
Principios de una buena jerarquía de topics MQTT
Todos los árboles siguientes siguen el mismo puñado de reglas. Conocerlas facilita adaptar los ejemplos a tu propio proyecto.
- De lo amplio a lo concreto. Pon primero el nivel más general (planta, hogar, flota) y al final el más específico (una sola medida o un comando).
- Profundidad fija por tipo de dato. Si la telemetría de todos los dispositivos está en el mismo nivel, un único patrón con
+la encuentra toda. - Separa los datos por dirección. La telemetría sube, los comandos bajan. Dales ramas distintas para que los dispositivos solo se suscriban a lo que necesitan.
- Minúsculas, sin espacios, sin barra inicial.
home/kitchen/tempyHome/Kitchen/Tempson topics distintos; una/inicial crea un primer nivel vacío. - Identificadores que sobrevivan a los cambios. Usa etiquetas de activo o números de serie, no nombres legibles que acaban renombrándose.
- Diseña para las suscripciones, no para el publicador. Anota las consultas con comodines que ejecutarán los consumidores antes de fijar el árbol.
El razonamiento detallado se explica en las convenciones de nombres de topics MQTT. Aquí nos centramos en árboles concretos.
Ejemplo de jerarquía de topics para un hogar inteligente
Un hogar tiene una estructura natural: las habitaciones contienen dispositivos, y los dispositivos exponen su estado y aceptan comandos.
home/<room>/<device>/state # estado actual, retenido
home/<room>/<device>/set # comando al dispositivo
home/<room>/<device>/availability # online/offline (Last Will)
home/<room>/<sensor>/<measurement> # lecturas numéricas
home/livingroom/lamp/state -> {"on": true, "brightness": 70}
home/livingroom/lamp/set -> {"on": false}
home/kitchen/climate/temperature -> 21.4
home/kitchen/climate/humidity -> 48
home/garage/door/state -> "closed"
home/garage/door/availability -> "online"
| Necesidad del consumidor | Suscripción |
|---|---|
| Todo lo de la cocina | home/kitchen/# |
| El estado de todos los dispositivos | home/+/+/state |
| Todas las lecturas de temperatura | home/+/+/temperature |
| Qué dispositivos están offline | home/+/+/availability |
Publica state y availability como mensajes retenidos para que un dashboard que arranque más tarde conozca de inmediato la situación actual. Los comandos no deben retenerse; de lo contrario, un dispositivo que se reinicie volverá a ejecutar el "abre la puerta del garaje" de ayer. Para un tratamiento más profundo de habitaciones, integraciones y el discovery de Home Assistant, consulta la guía de estructura de topics MQTT para el hogar inteligente.
Ejemplo de jerarquía de topics para una flota de vehículos
Los datos de una flota se organizan en torno a los vehículos, y los consumidores suelen querer o bien la imagen completa de un vehículo o bien un tipo de dato en toda la flota.
fleet/<region>/<vehicleId>/telemetry/<stream>
fleet/<region>/<vehicleId>/events/<eventType>
fleet/<region>/<vehicleId>/cmd/<command>
fleet/<region>/<vehicleId>/status
fleet/eu-west/van-0142/telemetry/gps -> {"lat": 51.51, "lon": -0.12, "spd": 34}
fleet/eu-west/van-0142/telemetry/engine -> {"rpm": 1800, "coolant": 88}
fleet/eu-west/van-0142/events/harsh-brake -> {"ts": 1792130400, "g": 0.52}
fleet/eu-west/van-0142/cmd/locate -> {}
fleet/eu-west/van-0142/status -> "online"
| Necesidad del consumidor | Suscripción |
|---|---|
| Mapa en directo de todos los vehículos | fleet/+/+/telemetry/gps |
| Todo lo de una camioneta de reparto | fleet/+/van-0142/# |
| Eventos de comportamiento al volante en una región | fleet/eu-west/+/events/# |
Decisiones que vale la pena copiar:
- La región antes que el vehículo. Permite dividir el procesamiento por regiones más adelante, por ejemplo con suscripciones compartidas por grupo de workers regional.
- Flujos en lugar de un payload gigante. El GPS cada segundo y los datos del motor cada treinta segundos no deberían forzarse en el mismo mensaje.
- Comandos por vehículo. Cada vehículo se suscribe a
fleet/<region>/<its id>/cmd/#y a nada más.
Ejemplo de jerarquía de topics para una fábrica
En la fabricación, la jerarquía de equipos ya existe en la documentación de la planta, así que el árbol debe reflejarla. Una versión simplificada:
<site>/<area>/<line>/<machine>/<namespace>/<detail>
plant1/assembly/line1/robot2/telemetry/joint-temps
plant1/assembly/line1/robot2/state
plant1/assembly/line1/robot2/alarms/overtemp
plant1/machining/line3/cnc1/telemetry/spindle
plant1/machining/line3/cnc1/cmd/stop
| Necesidad del consumidor | Suscripción |
|---|---|
| Servicio OEE de una línea | plant1/machining/line3/+/state |
| Vista de mantenimiento de todas las alarmas | plant1/+/+/+/alarms/# |
| Historian de toda la planta | plant1/# |
Mantén un vocabulario de namespaces pequeño y fijo: telemetry, state, alarms, events, cmd. Cuando un integrador inventa data, values y measurements para lo mismo, cada consumidor tiene que aprender tres patrones.
Ejemplo de jerarquía de topics para monitorización energética
Los proyectos energéticos mezclan contadores, inversores y baterías en varios edificios. El árbol separa la ubicación física de la magnitud energética que se mide.
energy/<site>/<building>/<meterId>/<quantity>
energy/campus-a/building-3/main-meter/power -> 42.7 (kW)
energy/campus-a/building-3/main-meter/energy -> 18233.4 (kWh)
energy/campus-a/building-3/pv-inverter-1/power -> 12.1
energy/campus-a/building-3/battery-1/soc -> 76
energy/campus-a/building-3/battery-1/cmd/mode -> "discharge"
Incluye las unidades en la documentación o en el payload, nunca en el propio topic. Un topic como .../power_kw pasa a ser incorrecto el día en que alguien publica vatios. Un payload JSON como {"v": 42.7, "unit": "kW", "ts": 1792130400} mantiene estable el topic y hace que la lectura se describa a sí misma.
Para terminar, un árbol de estilo ISA-95
Cuando un proyecto crece más allá de una planta o empieza a alimentar un Unified Namespace, suele converger en un árbol de estilo ISA-95: empresa, planta, área, línea, celda o máquina y, después, un namespace de datos. Es también la forma que usa ConnectMQ cuando vuelve a publicar datos Sparkplug B en topics legibles. Un mensaje Sparkplug en
spBv1.0/factory1/DDATA/line1/cnc1
se decodifica y se vuelve a publicar en
connectmq/factory1/production/line1/cnc1/telemetry
Eso te da un ejemplo completo de la estructura de destino:
<enterprise>/<site>/<area>/<line>/<machine>/<namespace>
connectmq/factory1/production/line1/cnc1/telemetry
connectmq/factory1/production/line1/cnc1/state
connectmq/factory1/production/line2/press4/telemetry
connectmq/factory1/quality/lab/cmm1/events
El portal de ConnectMQ reconoce los topics ISA-95 y Unified Namespace y muestra los dispositivos agrupados por esos niveles, así que un árbol disciplinado se nota directamente en la vista de dispositivos. El artículo sobre topics MQTT ISA-95 explica cada nivel y sus trampas, y la guía de Sparkplug B y Unified Namespace cubre cómo encajan ambos.
Comparativa de los cuatro árboles
| Proyecto | Nivel superior | Nivel de identidad | Datos divididos por | Profundidad típica |
|---|---|---|---|---|
| Hogar inteligente | home |
dispositivo en una habitación | state / set / medida | 4 |
| Flota | fleet |
vehículo en una región | telemetry / events / cmd | 4–5 |
| Fábrica | planta | máquina en una línea | namespace | 5–6 |
| Energía | energy |
contador en un edificio | magnitud | 5 |
La profundidad importa en los brokers reales. Algunos brokers limitan los niveles de topic, y cada nivel adicional cuesta bytes en cada mensaje. El broker público broker.connectmq.com, por ejemplo, permite hasta 8 niveles de topic, así que un prefijo de demostración como connectmq/demo/<id> deja cinco niveles para tu propio árbol.
Prueba un árbol en el broker público
Puedes prototipar cualquiera de estas jerarquías en el servidor MQTT público gratuito antes de comprometerte con ella. Usa un prefijo único, porque cualquiera puede leer el área pública, y mantén datos no sensibles: es un servidor para pruebas y prototipos, no para datos de producción.
# Suscriptor: todos los estados de dispositivo de tu hogar de demostración
mosquitto_sub -h broker.connectmq.com -p 1883 -i tree-sub-a91c \
-t 'connectmq/demo/a91c/home/+/+/state' -v
# Publicador: un estado de lámpara retenido
mosquitto_pub -h broker.connectmq.com -p 1883 -i tree-pub-a91c -r \
-t 'connectmq/demo/a91c/home/livingroom/lamp/state' \
-m '{"on": true, "brightness": 70}'
Ese ejemplo usa siete niveles, lo que encaja dentro del límite del broker público. Si el suscriptor ve el estado de la lámpara, tu plan de comodines funciona. Después prueba connectmq/demo/a91c/home/livingroom/# y confirma que solo devuelve el salón. Si el árbol es nuevo para ti, la guía de comodines MQTT explica exactamente cómo coinciden + y # con cada nivel, y el tutorial de MQTT cubre los fundamentos de publicación y suscripción.
Errores habituales en las jerarquías de topics
- Poner primero el tipo de dato.
temperature/kitchendispersa cada dispositivo por muchas ramas y complica las suscripciones por dispositivo. - Codificar valores en los topics. Usar
home/lamp/onyhome/lamp/offcomo topics obliga a los consumidores a suscribirse a ambos; publica el valor como payload. - Un topic por ID de mensaje o marca de tiempo. Los topics son direcciones, no registros. Los topics únicos por mensaje inflan el almacenamiento de retenidos y las listas de topics.
- Separadores mezclados.
line-1,line_1yLine1en el mismo árbol acabarán rompiendo el comodín de alguien. Elige un estilo. - Sin rama de comandos. Si los comandos comparten topic con la telemetría, los dispositivos reciben de vuelta sus propios datos y necesitan filtrado adicional.
Empieza con ConnectMQ
Cuando tu árbol esté listo para dispositivos reales, ejecútalo en un broker MQTT gestionado con TLS y credenciales privadas; la guía de broker MQTT en la nube explica las opciones. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y observa cómo se va llenando tu jerarquía con el explorador de topics en directo y la vista de dispositivos ISA-95.
Preguntas frecuentes
¿Qué profundidad debe tener una jerarquía de topics MQTT?
La suficiente para identificar el origen y el tipo de dato, normalmente entre cuatro y seis niveles. Más niveles añaden bytes a cada mensaje y pueden chocar con los límites del broker sin aportar una estructura útil.
¿Debe ir primero el ID del dispositivo o el tipo de dato?
Pon primero la ubicación y la identidad del dispositivo, y después el tipo de dato. Así todos los datos de un dispositivo quedan bajo una misma rama y los comodines + siguen pudiendo seleccionar un tipo de dato en todos los dispositivos.
¿Puedo cambiar mi jerarquía de topics más adelante?
Sí, pero todos los publicadores y suscriptores tienen que cambiar con ella. Una vía de migración habitual es publicar en el árbol antiguo y en el nuevo durante un periodo de transición, y retirar el antiguo cuando los consumidores se hayan trasladado.
¿Necesito ISA-95 para un proyecto pequeño?
No. Un árbol sencillo como el del ejemplo del hogar inteligente es suficiente para proyectos pequeños. Los árboles de estilo ISA-95 compensan cuando varias plantas, equipos o sistemas comparten un mismo namespace.
